obsidian-mcp

Give Claude (and any MCP client) real agent access to your Obsidian vault — graph traversal, Dataview queries, daily-note awareness, and more.

Install · Tools · Prompts to try · How it compares · FAQ

Most Obsidian MCP servers expose read_file and write_file and call it a day. This one treats your vault as a knowledge graph — your LLM gets backlinks, forward links, Dataview queries, daily notes, and multi-hop graph traversal in a single call.

Why

You opened Claude Desktop, asked it to find connections in your notes, and watched it read_file its way through your vault one note at a time. That's not how Obsidian users actually think about their notes. The graph is the value — backlinks, transitive connections, tags, Dataview-typed metadata. This server exposes all of it as first-class tools.

Install

You need the Local REST API plugin in Obsidian. Install it from Community Plugins, enable it, and copy the API key from its settings.

Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp"],
      "env": {
        "OBSIDIAN_API_KEY": "paste-your-key-here"
      }
    }
  }
}

Restart Claude Desktop. You're done.

Claude Code

claude mcp add obsidian -e OBSIDIAN_API_KEY=paste-your-key-here -- npx -y obsidian-mcp

Cursor / Cline / Continue / Zed

Any MCP-compatible client works. Point it at npx -y obsidian-mcp with OBSIDIAN_API_KEY in the environment.

From source

git clone https://github.com/yanxue06/obsidian-mcp.git
cd obsidian-mcp
npm install
npm run build
OBSIDIAN_API_KEY=... node dist/index.js

Prompts to try

Drop these into Claude Desktop with the server connected:

Build me a Map of Content for everything I've written about distributed systems. Use traverse_graph from "Distributed systems.md" with depth 2, then group the neighbors thematically and write the MOC to MOCs/Distributed systems MOC.md.

Find every note tagged #project where status != "done" and the due date is this week. Use query_dataview.

What's in my daily note today? Anything I forgot to follow up on from yesterday's note?

Find all my orphan notes in Inbox/. For each one, suggest where it belongs based on its content and existing tags.

I'm renaming "Atomic notes.md" to "Evergreen notes.md". Find every note that links to it and tell me which ones I'd need to update.

Walk the graph 2 hops out from "Working memory.md" and tell me which notes are most central to my thinking on attention.

Tools

15 tools total. The differentiated ones are in bold.

Reading

Search & graph

Writing

How it compares

Configuration

All config is via environment variables — set them in your MCP client config.

How it works

┌──────────────┐     stdio (MCP)      ┌──────────────┐    HTTPS     ┌──────────────────┐
│ Claude / IDE │ ───────────────────► │ obsidian-mcp │ ───────────► │  Local REST API  │ ──► Vault
└──────────────┘                      └──────────────┘              │ (Obsidian plugin)│
                                                                    └──────────────────┘

obsidian-mcp is a thin layer over the Local REST API plugin. The plugin runs an HTTPS server inside Obsidian with full vault access; this server adapts that surface into the MCP protocol and adds graph-aware tools that Obsidian's REST API doesn't expose directly (backlinks, multi-hop traversal, orphan detection).

Everything is local. No data leaves your machine except the requests your MCP client makes to its model provider — and you control that.

FAQ

Do I need to install an Obsidian plugin? Yes — the Local REST API plugin. It's the only sane way to talk to a running vault from outside. Once installed, obsidian-mcp itself runs as a separate Node process started by your MCP client; you don't install another plugin in Obsidian for this.

Does it work if Obsidian is closed? No. The Local REST API runs inside Obsidian, so the app needs to be open.

Does it support multiple vaults? One server instance points at one running Obsidian instance. Run multiple MCP server entries (different names + different ports) if you switch vaults frequently.

Why HTTPS by default with OBSIDIAN_VERIFY_TLS=false? The plugin ships a self-signed cert. The traffic is loopback-only (127.0.0.1), so verification adds friction without a real security gain. If you've replaced the cert, set the flag.

Is this safe? The MCP server gives the model whatever access the API key grants. Anything the model is willing to delete, it can delete. Treat it like any agent with file write access — review what it's about to do, especially before bulk operations.

Roadmap

• Embedding-based semantic search (currently keyword-only via the plugin)

• Workspace switching / multi-vault routing

• Read-only safe mode (no write tools registered)

• Resource subscriptions (push updates when notes change)

• Smithery / mcp-get registry submission

PRs welcome. See CONTRIBUTING.md.

Acknowledgements

• Local REST API by @coddingtonbear — this entire project is downstream of it.

• The Model Context Protocol team at Anthropic.

License

MIT — see LICENSE.