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

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

Claude Desktop

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

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

Claude Code

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

Tools (12)

Reading & Discovery

Graph Traversal

Writing & Manipulation

Configuration

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

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

CLI Flags

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

How It Works

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

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

Development

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

License

MIT