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_noteauto-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
| 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:
{
"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
- On startup, scans all
.mdfiles 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
npm install
npm test # Run 66 tests
npm run build # Build to dist/
npm run dev -- --vault test/fixtures/vault # Dev mode
License
MIT