Obsidian MCP Server

Empower your AI agents and development tools with seamless Obsidian integration!

An MCP (Model Context Protocol) server providing comprehensive access to your Obsidian vault. Enables LLMs and AI agents to read, write, search, and manage your notes and files through the Obsidian Local REST API plugin.

🔌 Connection Modes & Performance

The Obsidian MCP Server uses a Hybrid Bridge architecture to provide the best balance between stability and performance.

| Mode | Performance | Key Features | Requirement | | :------------------ | :------------- | :-------------------------------------------- | :----------------------------- | | CDP (Native) | 🔥 Instant | Native Dataview, UI Control, O(1) Search/Move | --remote-debugging-port=9222 | | REST (Fallback) | 🧱 Stable | Standard file operations, Cross-platform | Local REST API Plugin |

Hybrid Capability: Tools automatically use CDP when available. Every hybrid tool response includes a source field ("cdp", "rest", or "cache") to inform agents about the data source and performance level.

Built on the cyanheads/mcp-ts-template, this server follows a modular architecture with robust error handling, logging, and security features.

🚀 Core Capabilities: Obsidian Tools 🛠️

This server equips your AI with specialized tools to interact with your Obsidian vault:

Note Management

| Tool Name | Description | Key Features | | :------------------------ | :------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------- | | obsidian_search_replace | Performs search-and-replace operations within a note. | - Supports string or regex search.- Sequential replacements. | | obsidian_move_folder | Moves or renames folders with link tracking. | - Atomic folder move via CDP.- Updates all links pointing to notes inside the folder. |

Search & Navigation

| Tool Name | Description | Key Features | | :----------------------------- | :---------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | | obsidian_quick_switcher_plus | Native search & navigation driver (CDP). | - Supports shorthand: #headings, >commands, $symbols, files.- Automatically extracts suggestions from the UI. (Native Only) | | obsidian_fuzzy_search_notes | Finds notes using fuzzy filename matching. | - Similar to Obsidian Quick Switcher.- Supports partial matches, typos, subsequences.- Returns top matches ranked by relevance. |

Metadata & Advanced Features

| Tool Name | Description | Key Features | | :---------------------------- | :--------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- | | obsidian_manage_frontmatter | Manages a note's YAML frontmatter. | - get, set, or delete frontmatter keys (supports structured values). | | obsidian_manage_tags | Adds, removes, or lists tags for a note. | - Frontmatter and inline tag support. | | obsidian_execute_dataview | Executes Dataview queries. | - Native DQL/DataviewJS support (via CDP).- Strict Requirement: Requires CDP connection. | | obsidian_get_metadata_cache | Accesses native metadata cache. | - Real-time vault stats, tags, and link graph (via CDP). | | obsidian_get_day_schedule | Fetches unified chronological schedule. | - Aggregates tasks from all files for a specific date using Dataview.- Extracts time-blocks. | | obsidian_update_day_planner | Manages daily note schedule. | - Intelligently updates the ## Day planner section.- Strictly 24h format. | | obsidian_get_three_day_plan | High-level planning wrapper. | - Aggregates schedule for today, tomorrow, and the day after. | | obsidian_get_ui_snapshot | Captures UI state (Tree + Screenshot). | - Returns structural JSON and saves PNG to backups/debug/. (Native Only) | | obsidian_ui_action | Performs native UI interactions. | - click, type, hover, scroll. (Native Only) | | obsidian_render_html | Renders a markdown file to HTML. | - Syntax highlighting for code blocks.- Useful for viewing note structure. | | obsidian_validate_mermaid | Validates mermaid diagram syntax. | - Uses mermaid-cli for validation.- Returns rendered SVG if successful. |

Resources

| Resource URI | Description | | :------------------------- | :------------------------------------------------------------------------------- | | obsidian://server/status | Dynamic server status including connection modes, capabilities, and vault stats. |

🚀 "God Mode": Native CDP Integration

This server now supports Hybrid Bridge architecture, combining the stability of the REST API with the native power of the Chrome DevTools Protocol (CDP).

Benefits of CDP Mode

• Full Dataview Support: Execute complex DQL and even dataviewjs queries natively.
• Native Performance:
• Instant Moves: obsidian_move_folder uses native file manager (O(1) with auto-link tracking).
• UI Interaction: Control Obsidian's UI, panels, and other plugins directly.

Enabling CDP Mode

1. Start Obsidian with Remote Debugging:

   • Close Obsidian.

   • Start it from the command line with the port flag:

     # macOS
     /Applications/Obsidian.app/Contents/MacOS/Obsidian --remote-debugging-port=9222
     
     # Windows
     %LocalAppData%\Obsidian\Obsidian.exe --remote-debugging-port=9222
     
     # Linux
     obsidian --remote-debugging-port=9222

2. Update .env:

   OBSIDIAN_CDP_ENABLED=true
   OBSIDIAN_CDP_PORT=9222

3. Restart the MCP Server.

The server will automatically detect if CDP is available. If not, it gracefully degrades to REST-only mode.

🛠️ Troubleshooting CDP Connection

If you encounter errors stating that CDP is required or connection failed:

1. Check for Port Conflicts: Be aware that CDP only allows one active client connection at a time to port 9222.
   • Close other tools that might be using the port (e.g., MCP Inspector, Chrome DevTools, or other MCP server instances).
2. Restart Services:
   • Completely close and restart Obsidian.
   • Restart your AI agent / client (e.g., Opencode).
3. Verify Configuration: Ensure Obsidian was started with the --remote-debugging-port=9222 flag and your .env file has OBSIDIAN_CDP_ENABLED=true.

🛡️ Safety Features

This server includes a robust safety layer to protect your data, especially when used with AI agents that might make mistakes.

1. Write Protection Modes

• off: Read-only. No modifications allowed.
• safe (Default): Backups created before every write. Conflict detection enabled.
• confirm: The server will ask for confirmation (via MCP response) before every write.
• full: No restrictions. Use with caution.

2. Automatic Backups

Every time a file is modified or deleted, a backup is automatically created in the backups/ directory. Backups are retained for 30 days by default.

3. Conflict Detection

The server checks the last modification time of a file before writing. If it was modified recently (e.g., within 30 seconds), it will reject the write to prevent overwriting your manual changes or sync conflicts.

4. Operation Logging & Undo

Every write action performed by the agent is logged. You can query the history and undo any operation using its unique ID. The agent can see the last 7 days of its own history.

🚀 Installation & Setup

Prerequisites

1. Obsidian: Installed and running.
2. Obsidian Local REST API Plugin: Install here.
3. API Key: reveal and copy from plugin settings.
4. Mermaid CLI (Optional): npm install -g @mermaid-js/mermaid-cli for mermaid validation.

Configuration

Add to your MCP client settings (e.g., claude_desktop_config.json):

Option 1: Using npx (Recommended — no install)

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@krisspyw/obsidian-mcp-server"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "OBSIDIAN_BASE_URL": "https://127.0.0.1:27124",
        "OBSIDIAN_VERIFY_SSL": "false",
        "WRITE_MODE": "safe",
        "BACKUP_ENABLED": "true"
      }
    }
  }
}

Option 2: Using a local build

If you cloned this repo and built it locally:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "OBSIDIAN_BASE_URL": "https://127.0.0.1:27124",
        "OBSIDIAN_VERIFY_SSL": "false",
        "WRITE_MODE": "safe",
        "BACKUP_ENABLED": "true"
      }
    }
  }
}

🛠️ Development

Setup Test Vaults

Run the provided script to set up community example vaults for safe testing:

./scripts/setup-vaults.sh

Build & Test

npm install
npm run build
npm test          # Run unit tests (Vitest)
npm run inspect   # Start MCP Inspector

🧪 Experimental Features

These features are planned but not implemented. They represent advanced capabilities for future development.

Semantic Search with RAG (Not Implemented)

Goal: Enable agents to understand vault content semantically (meaning-based, not just keyword matching).

Current limitation: Agents can only use keyword search (CLI search) and link-based navigation. They lack semantic understanding.

What this adds:

• Find notes by meaning, not just exact words
• Understand vault themes and clusters
• Retrieve contextually relevant information
• Enable "related notes" discovery beyond explicit links

References & Inspiration:

• Obsidian Copilot: Search and Knowledge Retrieval

See IMPLEMENTATION_PLAN.md - Phase 9 for full implementation details including:

• Embedding provider options (OpenAI, Anthropic, local)
• Vector storage approach
• Background indexing process
• Configuration examples

Status: Not started (Experimental - Opt-in only, disabled by default)

License

Apache License 2.0 - see LICENSE for details.