Obsidian MCP Server: Connect Your Notes to AI Coding Agents

What an Obsidian MCP Server Does

An Obsidian MCP server exposes your vault to AI agents through the Model Context Protocol. The agent can read notes, search across your vault, create new files, and edit existing ones. All operations happen locally on your machine.

The practical value: instead of pasting context into prompts, the agent pulls what it needs. Ask it to reference your architecture decision records while reviewing code. Have it search your meeting notes for the API spec discussion from last week. Let it update your project docs after making code changes.

Server Comparison

Five implementations dominate. They split into two architectural camps: REST API servers that require the Obsidian Local REST API plugin (and Obsidian to be running), and filesystem servers that read markdown directly.

REST API vs Filesystem Access

REST API servers (mcp-obsidian, obsidian-mcp-server) connect through the Obsidian Local REST API plugin. Obsidian must be open. The upside: Obsidian mediates all file operations, so the server can't bypass Obsidian's file handling. The downside: you need the plugin installed and configured, and you need an API key.

Filesystem servers (obsidian-mcp, MCPVault) read and write markdown files directly. Obsidian doesn't need to be running. Setup is simpler since you just point the server at your vault directory. The tradeoff: changes made while Obsidian is open might conflict with Obsidian's own file watchers, though in practice this rarely causes issues.

Top 5 Implementations

1. mcp-obsidian (Python, REST API)

The most starred Obsidian MCP server. Written in Python, installed via uvx. Connects through the Local REST API plugin on port 27124 (HTTPS) or 27123 (HTTP).

Tools: list_files_in_vault, list_files_in_dir, get_file_contents, search, patch_content, append_content, delete_file

Best for: Python-centric setups, users who already have the REST API plugin installed, Claude Desktop users (most documentation targets this client).

2. MCPVault (TypeScript, Filesystem)

Focuses on safety and efficiency. Automatically excludes the .obsidian system directory. Uses BM25 relevance ranking for search results, produces 40-60% smaller responses through minified field names, and supports batch operations across multiple notes.

Tools: 14 methods covering read, write (overwrite/append/prepend), patch, delete, move, search, frontmatter management, tag management, directory listing, and vault statistics.

Best for: token-conscious usage, batch operations, users who want the server running without Obsidian open.

3. obsidian-mcp (TypeScript, Filesystem)

The simplest setup of any Obsidian MCP server. One argument: your vault path. Supports multiple vaults by passing additional paths. Includes comprehensive tag management with vault-wide rename operations.

Tools: read-note, create-note, edit-note, delete-note, move-note, create-directory, search-vault, add-tags, remove-tags, rename-tag, manage-tags, list-available-vaults

Best for: quick setup, multi-vault users, developers who want direct filesystem access without plugins.

4. obsidian-mcp-server (TypeScript, REST API)

Adds an intelligent caching layer on top of the REST API. The cache refreshes periodically (configurable, default 10 minutes) and provides fallback search when the API is unavailable. Supports case-insensitive path matching to prevent errors from path mismatches.

Tools: obsidian_read_note, obsidian_update_note, obsidian_search_replace, obsidian_global_search, obsidian_list_notes, obsidian_manage_frontmatter, obsidian_manage_tags, obsidian_delete_note

Best for: large vaults where caching improves performance, users who want both HTTP and HTTPS transport options, teams needing JWT/OAuth authentication.

5. Semantic MCP Plugin (Native Obsidian Plugin)

The only implementation that runs inside Obsidian as a native plugin. This gives it access to Obsidian's internal APIs: the knowledge graph, Dataview queries, link traversal, and backlink analysis. Install it from Obsidian's Community Plugins browser.

Tools: 8 groups covering vault operations, content editing, graph intelligence, Dataview queries, database operations, workflow suggestions, view navigation, and system status.

Best for: users with heavily linked vaults, Dataview users, anyone who needs graph-aware operations like finding paths between notes or analyzing backlink clusters.

Configuration

Claude Code

Add the server to your Claude Code MCP settings. For filesystem-based servers, the config is minimal:

// ~/.claude.json (filesystem-based, no API key needed)
{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp", "/path/to/your/vault"]
    }
  }
}

For REST API-based servers, you need the API key from the Obsidian Local REST API plugin settings:

// ~/.claude.json (REST API-based)
{
  "mcpServers": {
    "obsidian": {
      "command": "uvx",
      "args": ["mcp-obsidian"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key-here",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

Cursor

Cursor supports MCP servers through its settings. The configuration format is the same JSON structure. Go to Cursor Settings, find the MCP section, and add the server config:

// Cursor MCP settings
{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@bitbonsai/mcpvault@latest", "/path/to/your/vault"]
    }
  }
}

Claude Desktop

Edit the config file at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows). Same JSON format as above.

Multiple Vaults

obsidian-mcp supports multiple vaults natively by passing additional paths:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp", "/path/to/work-vault", "/path/to/personal-vault"]
    }
  }
}

For other servers, create separate entries with distinct names (obsidian-work, obsidian-personal).

Use Cases for Developers

Practical Workflow Example

You're refactoring an authentication module. The agent reads your ADR on auth architecture from Obsidian, searches your vault for related meeting notes, then cross-references with the actual codebase. It proposes changes that align with both the documented architecture and the existing code patterns.

Without the Obsidian MCP server, the agent sees only code. With it, the agent sees code plus the reasoning behind the code. Better context produces better changes.

Security Considerations

Connecting your personal knowledge base to an AI agent is a meaningful security decision. The server runs locally, but the AI model processes note contents as part of its context window, which means note content gets sent to the model provider.

Obsidian for Knowledge, WarpGrep for Code

Obsidian MCP servers solve half the context problem: they give AI agents access to your documentation, specs, and notes. The other half is the codebase itself. An agent that can read your architecture notes but can't search the code intelligently is still working with partial context.

WarpGrep is an MCP server for codebase search. It indexes your code and lets agents find relevant files by meaning, not just keyword matching. Together, the two servers cover the full picture:

Running both MCP servers gives the agent complete context. It reads your spec in Obsidian, finds the relevant code with WarpGrep, and makes changes that align with both. Cognition measured that coding agents spend 60% of their time searching for context. Giving them structured access to both knowledge and code cuts that overhead.

Frequently Asked Questions

Does Obsidian need to be running for the MCP server to work?

Depends on the server. REST API servers (mcp-obsidian, obsidian-mcp-server) require Obsidian open with the Local REST API plugin enabled. Filesystem servers (obsidian-mcp, MCPVault) read files directly and work without Obsidian running. The Semantic MCP plugin runs inside Obsidian, so yes for that one.

Can an Obsidian MCP server modify my notes?

Yes. Most implementations support create, edit, append, and delete operations. Back up your vault before enabling write access. Use git for version control on your vault so you can revert any unwanted changes.

Which server works with Claude Code?

All five work with Claude Code. The simplest options are obsidian-mcp (npx obsidian-mcp /path/to/vault) and MCPVault (npx @bitbonsai/mcpvault@latest /path/to/vault) since they need no plugins or API keys.

Can I connect multiple Obsidian vaults?

obsidian-mcp supports multiple vaults natively by passing additional paths as arguments. For other servers, create separate entries in your MCP config with distinct names.

Is it safe to give an AI agent access to my vault?

The server runs locally, but note content gets sent to the AI model as context. Scope access to specific directories, avoid storing credentials in vault files, keep sensitive notes in a separate vault, and use git so every change is reversible.

Related Guides

• CLAUDE.md Guide for Claude Code
• Claude Code Worktrees
• Claude Code vs Cursor
• Best Cursor Alternatives 2026