obsidian-mcp

Treat your Obsidian vault as a knowledge graph that AI agents can actually use.

A Model Context Protocol server that gives Claude — and any other MCP-compatible AI — graph-aware access to your notes. Backlinks, multi-hop traversal, Dataview queries, daily-note awareness, batch note creation, and safe rename-with-backlink-rewrite, exposed as 25 typed tools.

Setup · What you can do · Tools · Configuration · FAQ

Why this exists

Most "Obsidian + AI" integrations expose read_file and write_file, then ask the model to figure out the rest. That works for a five-note vault. It collapses on a 5,000-note vault the moment you ask anything graph-shaped — "what connects these two ideas?", "what have I forgotten to follow up on?", "reorganize this folder." Each question becomes a chain of dozens of read_file calls, blowing through your context window before the model has even started thinking.

obsidian-mcp exposes the graph itself as tools:

• get_note returns content + backlinks + forward links + tags + frontmatter in one call.

• traverse_graph walks N hops out from any starting note in one call — forward, backward, or both — returning nodes and edges as a subgraph.

• query_dataview passes Dataview DQL straight through, so the model can ask "all notes tagged #project where status != done sorted by due date" as a single typed query.

• move_note renames a note and rewrites every incoming wiki-link so the graph survives the rename. This unblocks the entire "reorganize my vault" class of prompts that other servers can't safely do.

• create_notes creates many notes in a single tool call — useful for bootstrapping an MOC plus its topical notes without paying N round-trips.

It's a small server (TypeScript, ~2,000 LOC, three runtime deps), runs locally over stdio, and works with Claude Desktop, Claude Code, Cursor, Cline, Continue, and Zed.

What you can do with it

Real prompts you can drop into Claude Desktop after installing:

Build an index note (Map of Content). Build me an index note for everything I've written about distributed systems. Use traverse_graph from "Distributed systems.md" with depth 2, cluster the neighbors thematically, and write the result to MOCs/Distributed Systems MOC.md. (MOC = Map of Content, a curated index note — Obsidian convention.)

Surface forgotten work. Find every note tagged #project where status != "done" and the due date is this week. (Single query_dataview call.)

Daily review. What's in my daily note today? Anything I forgot to follow up on from yesterday's note? Append my action items to today.

Inbox triage. Find all my orphan notes in Inbox/. For each one, read it, suggest where it belongs, and ask me before moving anything.

Bootstrap a topic. I just started studying transformer architectures. Use create_notes to scaffold a MOCs/Transformers MOC.md plus stub notes for "Self-attention", "Multi-head attention", "Positional encoding", and "Layer normalization", each linking back to the MOC.

Safe refactor. Rename "Atomic notes.md" to "Evergreen notes.md" using move_note. Update every backlink so nothing breaks.

Vault analytics. Run get_vault_stats and list_tags. Tell me my top 5 topics by note count, where I write most, and how my vault has grown.

Cross-domain synthesis. Walk 2 hops from "Working memory.md" and 2 hops from "Attention.md". Tell me which notes appear in both neighborhoods — those are my cross-cutting ideas.

If a workflow doesn't fit one of the existing tools, open an issue — the tool catalog below covers what's there today.

Setup

You need three things wired up: Obsidian running, the Local REST API plugin enabled, and your MCP client pointed at obsidian-mcp. The whole flow takes about a minute.

Step 1 — Install the Local REST API plugin in Obsidian

obsidian-mcp reaches your vault through the Local REST API community plugin. You only do this once per vault.

1. In Obsidian, open Settings → Community plugins → Browse.

2. Search for Local REST API, then Install and Enable it.

3. Open the plugin's settings tab. Copy the API key shown at the top — you'll paste it into your MCP client config in Step 2.

Step 2 — Add obsidian-mcp to your MCP client

Pick your client below.

Open the config file (create it if it doesn't exist):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Add the obsidian entry under mcpServers:

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

Quit and reopen Claude Desktop. You should see a tool icon in the input area — click it to confirm the obsidian tools are listed.

Run once, from any directory:

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

Then fully quit and reopen Claude Code (/mcp reconnect doesn't always re-spawn the child process). Verify with /mcp — obsidian should report ✓ Connected.

Add a new stdio MCP server with:

• Command: npx

• Args: -y @yanxue06/obsidian-mcp

• Env: OBSIDIAN_API_KEY=paste-your-key-here

Refer to your client's MCP config docs for the exact field names. Any MCP-compatible client works.

Step 3 — Verify it's wired up

In your MCP client, ask:

"Run get_vault_stats and tell me how many notes I have."

If you get a number back, you're done. If you hit a connection error, check troubleshooting below.

Troubleshooting

Tool catalog

25 tools, organized by category. Bold rows are the differentiators that other Obsidian MCP servers don't expose.

Discovery — find what's in the vault

Reading — get content out

Graph — walk and analyze the link structure

Writing — create and modify notes

UI / commands — drive Obsidian itself

How it works

┌──────────────────┐    stdio (MCP)    ┌──────────────┐    HTTPS     ┌──────────────────┐
│ Claude / Cursor  │ ─────────────────► obsidian-mcp ────────────────►  Local REST API  │ ──► Vault
│ Cline / Zed / …  │                   │  (this repo) │              │ (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, safe rename, batch creation).

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

Configuration

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

Performance & scale

*find_orphans and find_broken_links accept a sample_size parameter — bound them on large vaults to keep tool calls under the model's per-call timeout.

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. 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) if you switch vaults frequently. Multi-vault routing may come later.

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 — including delete and overwrite. Treat it like any agent with file write access: review what it's about to do, especially before bulk operations. move_note is designed for exactly this — making the safe path the default.

What about concurrency and crashes? No write-locking and no transaction semantics. If two agents touch the same file simultaneously, the loser's change is lost. move_note deletes the source after rewriting backlinks, and create_notes is best-effort per entry, so a crash mid-operation can leave partial state. Fine for interactive agent use; not appropriate for unattended batch jobs.

How do I debug? Run node dist/index.js directly with your env vars and the server prints connection status to stderr. Send JSON-RPC messages on stdin to test. The MCP Inspector (npm) is the easiest way to poke at tools manually.

Contributing

PRs welcome. See CONTRIBUTING.md for the dev loop, tool-authoring conventions, and code-style expectations.

Acknowledgements

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

• The Model Context Protocol team at Anthropic.

• The Obsidian plugin community, who built the ecosystem this depends on.

License

MIT — see LICENSE.