obsidian-mcp

MCP server that turns any Obsidian vault into an AI-queryable knowledge graph.

What makes this different from the 24+ existing Obsidian MCP servers:

Graph-first — BFS, shortest path, connected components, bridge detection via [[wikilinks]]
Zero infrastructure — No database, no Obsidian running, no API keys
Vault-agnostic — Works with any existing vault, no required structure
Backlink-aware writes — move_note auto-updates all references across the vault
Tiny — 4 runtime dependencies, ~42KB bundle

Quick Start

Terminal

npx obsidian-mcp --vault ~/my-obsidian-vault

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

config.json

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

Claude Code

Terminal

claude mcp add obsidian -- npx -y obsidian-mcp --vault /path/to/vault

Tools (12)

Reading & Discovery

Tool	Description
`vault_stats`	Overview: total notes, tags, links, orphans, components, top tags/hubs
`read_note`	Full content + frontmatter + links + backlinks + sections
`search_notes`	Filter by tags, folder, frontmatter, keyword. All combinable

Graph Traversal

Tool	Description
`graph_neighbors`	Direct links + backlinks for a note
`graph_traverse`	BFS/DFS from a note, N hops deep with tag filtering
`graph_shortest_path`	Shortest link chain between two notes
`graph_analyze`	Components, orphans, bridges, hubs, dead links

Writing & Manipulation

Tool	Description
`create_note`	Create with content + frontmatter
`patch_note`	Append, prepend, or replace a section. Update frontmatter
`move_note`	Rename/move + auto-update all backlinks across vault
`delete_note`	Delete + report broken links
`manage_tags`	Add/remove/rename tags (vault-wide rename supported)

Configuration

Zero-config by default. Optional .obsidian-mcp.json in vault root:

config.json

{
  "ignore": ["templates/", "daily-notes/", ".trash/"],
  "watchDebounce": 100,
  "maxTraversalDepth": 10,
  "maxSearchResults": 500
}

CLI Flags

Code

--vault <path>       Path to Obsidian vault (required)
--verbose            Enable debug logging
--log-level <level>  error | warn | info | debug (default: info)

How It Works

On startup, scans all .md files and builds an in-memory graph (~1-3s for 1k notes)
File watcher detects changes and updates the graph incrementally (~5ms per change)
Claude queries the graph via MCP tools — no re-scanning needed
Write operations update both the filesystem and the graph atomically

Hardcoded exclusions: .obsidian/, .trash/, node_modules/

Development

Terminal

npm install
npm test              # Run 66 tests
npm run build         # Build to dist/
npm run dev -- --vault test/fixtures/vault  # Dev mode

License

MIT