obsidian-mcp

English | 中文

This project implements a Model Context Protocol (MCP) server for connecting AI models with Obsidian knowledge bases. Through this server, AI models can directly access and manipulate Obsidian notes, including reading, creating, updating, and deleting notes, as well as managing folder structures.

Created by huangyihe

• Prompt House: https://prompthouse.app/
• YouTube: https://www.youtube.com/@huanyihe777
• Twitter: https://x.com/huangyihe
• Community: https://t.zsxq.com/19IaNz5wK

• 🔗 Seamless Obsidian Integration: Direct access to Obsidian knowledge bases through MCP protocol
• 📝 Complete Note Management: Read, create, update, and delete notes with advanced text replacement
• 📁 Folder Operations: Create, rename, move, and delete folders with full hierarchy support
• 🔍 Intelligent Search: Full-text search across all file types with smart scoring
• 🤖 AI-Powered Analysis: NEW Strategic insights using TRILEMMA-PRINCIPLES framework
• 🔗 Auto Backlink Generation: NEW Intelligent detection and conversion of note names to wikilinks
• ⚡ Precision Editing: Advanced PATCH operations with heading and block-level targeting
• 🚀 Dual API Strategy: Obsidian REST API with filesystem fallback for maximum reliability
• 🎯 Context Optimization: Smart content summarization for LLM context length management
• 📊 Batch Processing: Efficient bulk operations with progress tracking

The MCP server provides the following comprehensive tools:

• list_notes: List notes in the Obsidian vault with optional folder filtering
  • NEW recursive parameter: Control whether to list files recursively in subdirectories (default: true)
  • Use recursive: false to list only files in the specified folder without subdirectories
• read_note: Read the content of a specific note in the Obsidian vault
• read_multiple_notes: Read content from multiple notes simultaneously for batch processing
• create_note: Create a new note in the Obsidian vault with full content
• delete_note: Delete a note from the Obsidian vault
• search_vault: Advanced search across all file types with filename and content matching
• move_note: Move or rename notes to new locations (supports all file types including PDFs)
• manage_folder: Complete folder CRUD operations (create/rename/move/delete)

• update_note: Enhanced Update content using text replacements OR precision insertion

  • Traditional text replacement mode
  • NEW Heading-based insertion (before/after/append/prepend)
  • NEW Block ID-based insertion with ^block-id support
  • NEW PATCH API integration with filesystem fallback

• auto_backlink_vault: 🔗 Auto Backlink Generation

  • Intelligently scan entire vault for note name mentions
  • Convert text references to wikilink format ([[note name]])
  • Smart pattern matching with false positive prevention
  • Configurable dry-run mode and batch processing

• notes_insight: 🧠 AI-Powered Strategic Analysis ⭐ NEW

  • Generate strategic insights using TRILEMMA-PRINCIPLES framework
  • Automatic topic-based note discovery and relevance ranking
  • AI-driven content summarization for context optimization
  • Structured analysis: constraint identification → assumption challenges → breakthrough solutions
  • Configurable parameters for analysis depth and scope

• Node.js (v16 or higher)
• Obsidian desktop application
• Obsidian Local REST API plugin (needs to be installed in Obsidian)

Choose the most suitable installation method based on your technical level and usage needs:

Suitable for: General users who want the simplest installation experience

Download the pre-built extension package: obsidian-mcp.dxt

Double-click the downloaded .dxt file and the system will automatically install the extension. Then fill in the configuration interface:

• Vault Path: Your Obsidian vault path (e.g., /Users/username/Documents/MyVault)
• API Token: Obsidian Local REST API plugin token
• API Port: API port number (default: 27123)

Suitable for: Node.js developers who want automatic updates and version management

Simply add the following configuration to your MCP client config file:

Using npx (recommended, no pre-installation required):

{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "npx",
      "args": [
        "@huangyihe/obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "OBSIDIAN_API_TOKEN": "your_api_token",
        "OBSIDIAN_API_PORT": "27123"
      }
    }
  }
}

Note: First run will automatically download the package, subsequent runs use cache, ensuring you always use the latest version.

Suitable for: Users who need customization, advanced control, or offline usage

Step 1: Global Install

npm install -g @huangyihe/obsidian-mcp

Step 2: MCP Client Configuration

{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "obsidian-mcp",
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "OBSIDIAN_API_TOKEN": "your_api_token",
        "OBSIDIAN_API_PORT": "27123"
      }
    }
  }
}

Step 1: Clone Repository

git clone https://github.com/newtype-01/obsidian-mcp.git
cd obsidian-mcp

Step 2: Install Dependencies

npm install

Step 3: Build Project

npm run build

Step 4: Configure Environment Variables

cp .env.example .env
# Edit .env file with your configuration

Step 5: Start Server

npm start

Using Docker Compose (Recommended)

# Configure environment variables
cp .env.example .env
# Edit .env file

# Start service
docker-compose up -d

Using Docker Command

# Build image
docker build -t obsidian-mcp .

# Run container
docker run -d \
  --name obsidian-mcp \
  --env-file .env \
  --network host \
  -v $(OBSIDIAN_VAULT_PATH):$(OBSIDIAN_VAULT_PATH) \
  obsidian-mcp

All installation methods require the following configuration:

• OBSIDIAN_VAULT_PATH: Path to your Obsidian vault
• OBSIDIAN_API_TOKEN: API token for Obsidian Local REST API plugin
• OBSIDIAN_API_PORT: API port for Obsidian Local REST API (default: 27123)

⚠️ Important: For remote NPM installation and global installation, you MUST use the OBSIDIAN_ prefix for environment variables. The variables VAULT_PATH, API_TOKEN without the prefix will not work correctly.

1. Install "Local REST API" plugin in Obsidian
2. Generate API Token in plugin settings
3. Note the port number (default 27123)

The project includes a test script to verify server functionality:

node test-mcp.js

• Use npm run dev to run the server in development mode
• Source code is located in the src directory

MIT

Pull Requests and Issues are welcome!

• Model Context Protocol
• Obsidian Local REST API