Summary
Exposes 12 tools that treat your Obsidian vault as a queryable graph, no Obsidian app or database required. Read and search notes with tag and frontmatter filtering, traverse the wikilink graph with BFS/DFS, find shortest paths between notes, and detect connected components or bridge nodes. Write operations include creating notes, patching sections, and moving files with automatic backlink updates across the entire vault. Scans your vault once on startup to build an in-memory graph, then watches for changes incrementally. Reach for this when you want Claude to navigate and manipulate your existing Obsidian knowledge base as a first-class graph structure rather than flat markdown files.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
13 tools
obsidian_list_files_in_dir1 params
Parameters* required
dirpathstringobsidian_list_files_in_vault
No parameter schema in public metadata yet.
obsidian_get_file_contents1 params
Parameters* required
filepathstringobsidian_simple_search2 params
Parameters* required
querystringcontext_lengthstringobsidian_patch_content5 params
Parameters* required
targetstringcontentstringfilepathstringoperationstringtarget_typestringobsidian_append_content2 params
Parameters* required
contentstringfilepathstringobsidian_put_content2 params
Parameters* required
contentstringfilepathstringobsidian_delete_file2 params
Parameters* required
confirmstringfilepathstringobsidian_complex_search1 params
Parameters* required
querystringobsidian_batch_get_file_contents1 params
Parameters* required
filepathsstringobsidian_get_periodic_note2 params
Parameters* required
typestringperiodstringobsidian_get_recent_periodic_notes3 params
Parameters* required
limitstringperiodstringinclude_contentstringobsidian_get_recent_changes2 params
Parameters* required
daysstringlimitstringobsidian-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
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Categories
Registryactive
Package@smammadov/obsidian-mcp
TransportSTDIO
UpdatedMar 17, 2026
