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.
Keeps your Mac awake while Claude Code, Codex or Cursor works. Lets it sleep when they are done.
Try free for 7 days →
Block distracting apps from your iPhone permanently without a 3rd party app. Free and open source.
Block now (100% free) →
Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Free an open-source skills that make AI coding agents easier to understand, verify, and control.
Download for free →
Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →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
context_lengthstringquerystringobsidian_patch_content5 params
Parameters* required
contentstringfilepathstringoperationstringtargetstringtarget_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
periodstringtypestringobsidian_get_recent_periodic_notes3 params
Parameters* required
include_contentstringlimitstringperiodstringobsidian_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
Keeps your Mac awake while Claude Code, Codex or Cursor works. Lets it sleep when they are done.
Try free for 7 days →Block distracting apps from your iPhone permanently without a 3rd party app. Free and open source.
Block now (100% free) →Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Free an open-source skills that make AI coding agents easier to understand, verify, and control.
Download for free →Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →Categories
Registryactive
Package@smammadov/obsidian-mcp
TransportSTDIO
UpdatedMar 17, 2026
