obsidian-mcp

Your agent, native in your Obsidian vault. MIT-licensed, local-first, MCP-native.

An MCP (Model Context Protocol) server plus a bundle of seven Claude Skills for Obsidian vaults. Lets Claude, Cursor, ChatGPT, and any MCP-capable agent read, search, write, link, and reason about your vault while respecting Obsidian's conventions (wikilinks, frontmatter, tags, daily notes, MOCs).

pipx install obsidian-mcp
obsidian-mcp install --client claude-desktop --vault ~/Vaults/main
# Restart Claude Desktop and ask: "What's in my vault?"

Why this exists

Most existing Obsidian-MCP wrappers are read-only file listers. Few of them respect Obsidian's conventions (wikilink graph semantics, frontmatter round-trip, tag hierarchies, daily-note path patterns, MOCs), and none ship a workflow-centric skill bundle.

This project does both:

1. MCP-native + filesystem-direct. Structured tool calls, cross-client portable (Claude Desktop, Cursor, Codex, ChatGPT). No Local REST API plugin dependency. The vault is just a folder; we read and write it directly.
2. Seven workflow-centric Claude Skills. kepano/obsidian-skills (Steph Ango / Obsidian's CEO) ships file-format primitives; our skills compose them into end-user rituals: daily-note synthesis, MOC building, orphan integration, tag-tree refactoring.
3. Round-trip safety as a hard requirement. Every note we touch is parsed, mutated, re-serialized, and verified byte-identical. We don't mangle your markdown. See the protocol.
4. Local-first. Vault content never leaves your machine except via the MCP transport, where it's returned only to the LLM you've explicitly chosen. See the privacy doc.

Complementary, not adversarial, to in-Obsidian AI plugins like Smart Connections and Copilot for Obsidian: those embed an LLM UI inside Obsidian; we let an agent outside Obsidian reach in. Use both.

What you can ask

> Summarize the threads in my last 90 days of daily notes about RAG research.
> Find orphan notes in my vault that should connect to my "second-brain" MOC.
> Build a Map of Content for "agent design", linking the 30 most relevant notes.
> Refactor my tag tree — I have #ai, #AI, and #artificial-intelligence all in use.
> What are the most central notes in my vault right now?
> Prep a writing scratchpad for an essay on "evals as a craft".
> Walk my Inbox folder and help me integrate yesterday's captures.
> Compare my Q1 and Q2 daily notes — what's the trajectory of my thinking?

Each maps to a tool (or skill) we ship. The full tool surface — 22 MCP tools — is documented in docs/tools.md.

Quickstart

1. Install

pipx install obsidian-mcp

Or in a Python environment:

pip install obsidian-mcp

2. Register with your client

# For Claude Desktop:
obsidian-mcp install --client claude-desktop --vault /path/to/your/vault

# For Cursor:
obsidian-mcp install --client cursor --vault /path/to/your/vault

The install command writes an entry to your client's config and preserves any other MCP servers you have configured. Restart the client to pick up the new server.

3. Verify

obsidian-mcp doctor --vault /path/to/your/vault

Reports vault topology, daily-note pattern, round-trip safety, and graph stats. If something is wrong, this is where it surfaces.

4. Ask

Open Claude Desktop / Cursor / your client of choice and ask one of the example queries above. The agent will discover the tools automatically.

Privacy

Your vault stays on your machine. Indexing, embeddings, and graph analysis run locally.

The only network traffic generated by obsidian-mcp itself is:

1. A one-time ~150MB download of the BAAI/bge-small-en-v1.5 embedding model from Hugging Face. After that, search runs offline. Set OBSIDIAN_MCP_OFFLINE=1 to refuse the download.
2. The MCP transport itself, which carries data only to the LLM you've chosen (e.g. api.anthropic.com). We never bind to non-loopback addresses.

No telemetry. No analytics. No error reporting. No "anonymous statistics." See docs/privacy.md for the full data-flow inventory and verification instructions.

Respects your conventions

• Round-trip safe. Every note we modify can be re-parsed and re-serialized with byte-identical output. Comments, scalar styles ("x" vs 'x' vs bare), key order, flow vs block YAML, trailing newlines, BOMs — all preserved. We use ruamel.yaml round-trip mode. (Why this matters)
• Wikilinks. Full grammar: [[Link]], [[Link|Alias]], [[Link#Heading]], [[Link#^block]], ![[embed]], ![[image.png|400]], intra-note shortcuts. Rename a note → every reference in the vault is rewritten with the alias and subpath preserved verbatim.
• Frontmatter. YAML round-trip. Plural-list reserved keys on write (aliases, tags, cssclasses); legacy singular forms tolerated on read.
• Tags. Hierarchical (#research/rag/eval). Cross-vault rename. Tag-tree refactor workflow built in.
• Daily notes. Auto-detects Periodic Notes → core Daily Notes → heuristic. Supports moment.js path templates.
• Dataview / Templater / Excalidraw. Read structure, never execute the JS. .canvas, .base, .excalidraw.md files are read-only by default — use a dedicated tool (post-v1) to mutate them.

The full convention spec is in docs/conventions.md.

Skill catalog

Each skill is a markdown SKILL.md file installed alongside your client's skills directory. They compose the MCP tools into common workflows.

| Skill | What it does | | --- | --- | | /daily-summary | Reads last N daily notes, surfaces 3–7 themes, drafts a synthesis note linking back to originals. | | /connect-ideas | Finds two notes that should be linked but aren't. Explains why and proposes the insertion. | | /find-orphans | Surfaces orphan notes near a topic; helps integrate them with per-orphan confirmation. | | /refactor-tag-tree | Detects case chaos (#AI/#ai/#Ai), near-duplicates, and singletons; walks you through consolidation. | | /build-MOC | Interactive Map-of-Content building. Static wikilinks default; Dataview opt-in. | | /review-and-link | Walks your recent notes / Inbox folder; per-note review with link suggestions. | | /prep-for-writing | Given a topic, gathers relevant notes + creates a writing scratchpad with quotes and citations. |

Source: skills/. Design spec: docs/skills.md.

Compared to ...

• Smart Connections: in-Obsidian UI plugin with embedded LLM chat. Complementary — they own the in-app UX; we own the out-of-app agent surface.
• Copilot for Obsidian: same shape — in-app UI plugin. Complementary.
• kepano/obsidian-skills: filesystem-direct Claude Skills for .md / .canvas / .base / obsidian-cli. We layer additively on top — our skills are workflows on top of kepano's file-format primitives, and we detect and defer to kepano's skills when present.
• cyanheads/obsidian-mcp-server (TypeScript, Apache-2.0): closest MCP-tool-depth competitor. They require the Local REST API plugin; we don't (filesystem-direct). They ship dev-internal skills; we ship end-user workflow skills.
• MarkusPfundstein/mcp-obsidian: highest stars by default-recommendation inertia. Generic file ops over the REST API plugin; no wikilink/frontmatter/daily-note semantics; no skills.

Full landscape recon in docs/competitive.md.

Power-user FAQ

Will this break my notes? No — that's the single thing we won't do. Every write goes through safe_write which (1) refuses to mutate .canvas / .base / .excalidraw.md / files containing Templater execution blocks; (2) verifies the proposed bytes re-parse and re-serialize byte-identically; (3) writes via atomic temp-file rename; (4) backs up the pre-write bytes to .obsidian-mcp/last-write.bak. If anything goes sideways, obsidian-mcp undo restores the last write. Protocol details.

Does it touch my Templater? We read the structure (so the LLM knows the file is a template) but we never execute Templater code, and we refuse to mutate files containing <%* ... %> execution blocks unless you pass force=true. Same posture for dataviewjs fences.

What about my Excalidraw drawings? Treated as opaque. We index the frontmatter and any wikilinks in the back-of-note Markdown; we never touch the Excalidraw scene payload below the fence.

Will it eat my hand-crafted YAML formatting? No. ruamel.yaml round-trip mode preserves comments, scalar styles ("x" vs 'x' vs bare), key order, flow-vs-block sequence style, and trailing newline counts. We verify byte-identity on every write.

Does it work while Obsidian has the file open? On Windows the OS file lock will block our write — we'll surface a clear error. On macOS/Linux the write succeeds at the filesystem level, but Obsidian's in-memory buffer may overwrite ours on save (this is a TOCTOU race we currently can't prevent). Best practice for v0.1: close Obsidian (or use it read-only) when running write-capable skills. Detection + opt-in --strict-locks refusal is on the v0.2 roadmap.

Does it run my Dataview queries? No. We parse them for structure (extracting link("X") references for the backlink graph) but we never execute DQL or DataviewJS. Plugin behavior changes; we don't keep up; users get burned.

What if my vault is 10,000 notes? Indexing on first run takes ~30s on a modern laptop. Subsequent runs use the cached index in .obsidian-mcp/. Search latency is <500ms.

Can I use this without Obsidian installed? Yes — your vault is just a folder of Markdown files. We detect Obsidian's config if present (for daily-note pattern detection), but it's optional.

Does it work with [Obsidian Sync / iCloud / Syncthing]? Yes. We don't sync; you handle that. We use atomic writes (os.replace) so a sync race can't leave a half-written file.

Does it write to my .obsidian/ folder? No. Our state lives in .obsidian-mcp/ at the vault root, parallel to .obsidian/. We READ specific files in .obsidian/ (app.json for link format, daily-notes.json and plugins/periodic-notes/data.json for periodic-note patterns). We never write there.

CLI reference

obsidian-mcp serve --vault PATH                  # Start the MCP server (stdio by default)
obsidian-mcp install --client {claude-desktop,cursor} --vault PATH
obsidian-mcp doctor --vault PATH                 # Sanity-check: walk, parse, round-trip, build indexes
obsidian-mcp roundtrip --vault PATH              # Verify every note round-trips byte-identically
obsidian-mcp undo --vault PATH                   # Restore the most recent safe_write backup
obsidian-mcp diff PATH --vault PATH              # Show diff against last-write backup
obsidian-mcp detect-vaults                       # List vaults known to your Obsidian config

Roadmap

• v0.1 (current): MCP server + 7 Skills + CLI. Cross-platform (macOS, Linux, Windows). Local-only.
• v0.2: Watchfiles-based incremental index updates (no manual reindex needed). dry-run subcommand for every write tool.
• v0.3: .canvas and .base dedicated tools (read + mutate via the format spec).
• v0.4: Logseq compatibility (separate logseq-mcp sister project, evaluated post-launch).
• v1.0: Stable API guarantee for tool signatures. Optional opt-in remote-embedding mode (OpenAI / Voyage / Cohere).

Not on the roadmap: a hosted obsidian-mcp.com, a commercial tier, an Obsidian-plugin counterpart in v1. The 90-hour scope can't absorb a plugin (separate manifest/build/UI/review pipeline), and a commercial tier directly contradicts the local-first posture.

Contributing

Bug reports, feature requests, and PRs are welcome. Good first issues are labeled in the issue tracker.

Run the test suite locally:

git clone https://github.com/obsidian-mcp/obsidian-mcp
cd obsidian-mcp
python -m venv .venv && . .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest -q
ruff check src tests

If your PR touches any code that reads or writes vault content, please add a test against the fixture vault in tests/fixtures/test-vault/. The round-trip property test runs on every PR.

License

MIT — see LICENSE.

Built with FastMCP, ruamel.yaml, bm25s, sentence-transformers, NetworkX, and typer.