README.md
Deep access to your Obsidian vault for structural analysis and retrieval.
obsidian-emergent-mcp
Most obsidian MCPs I have seen just re impliment the basic features "read note, write note, search for note by tag/keyword", better, but basically just the same as standard claude code tools.
An MCP server that gives Claude Code deep access to your Obsidian vault. 28 tools for searching, navigating, and analyzing your knowledge graph — structural analysis, semantic retrieval, timeseries tracking, and more.
Your vault becomes a live knowledge base that Claude can read, search, and reason about.
Install
From inside your Obsidian vault, run:
curl -fsSL https://raw.githubusercontent.com/Gassandrid/obsidian-emergent-mcp/main/install.sh | bash
This installs two Python files into your vault's .claude/ directory, sets up .mcp.json, and installs dependencies. The MCP server starts automatically when you open the vault in Claude Code.
Requirements
- Python 3.10+
- An Obsidian vault (must have
.obsidian/directory) - Claude Code CLI
This tool is only really useful if you are Git versioning your vault, dont use this if you are not.
Smart connections will also add some more behavior. we dont use it for RAG but rather just cosine sim for related notes.
Tools
Search & Read
| Tool | What it does |
|---|---|
vault_rag |
Primary retrieval. Free-text query → TF-IDF + embedding reranking → ranked results with excerpts |
vault_search |
Substring search across titles, content, tags — for exact lookups |
vault_read |
Read a note's content, tags, and link counts |
Graph Navigation
| Tool | What it does |
|---|---|
vault_backlinks |
What links TO this note |
vault_forward_links |
What this note links TO |
vault_context |
Semantically related notes (embeddings + link proximity) |
vault_related |
Structurally related notes (shared neighbors) |
vault_hubs |
Most connected notes in the vault |
vault_orphans |
Notes with no links in or out |
Timeseries (git-backed)
| Tool | What it does |
|---|---|
vault_attention_flow |
What topics you're focused on — edits grouped by tag/folder with trend detection |
vault_topic_timeline |
How a knowledge domain grows over time — edits bucketed by week/month/day |
vault_note_history |
Full edit history of a specific note — commits, word counts, link counts at each snapshot |
vault_diff |
Structural diff: new/deleted notes, link changes over N days |
vault_recent |
Recently modified notes |
vault_knowledge_velocity |
Which notes are being edited most |
vault_link_weights |
Link strength via co-edit frequency |
Structure Analysis
| Tool | What it does |
|---|---|
vault_clusters |
Community detection via label propagation |
vault_concept_gaps |
Structural holes: missing notes, stub hubs, bridge gaps |
vault_broken_links |
Broken wikilinks with inferred topic tags, filterable |
vault_maturity |
Score notes by development maturity (word count, links, recency) |
vault_prereq_tree |
Learning dependency tree from a root note |
vault_stats |
Global metrics: note/link counts, tag distribution |
vault_tags |
Tag frequency with example notes |
vault_suggest_links |
Find semantically similar but unlinked note pairs |
vault_batch_tag |
Preview bulk tag operations (dry-run only) |
vault_open_questions |
Extract unresolved questions, TODOs, unchecked checkboxes |
Agent Memory
| Tool | What it does |
|---|
Tools (26)
vault_ragPerforms free-text query retrieval using TF-IDF and embedding reranking.vault_searchPerforms substring search across titles, content, and tags.vault_readReads a note's content, tags, and link counts.vault_backlinksRetrieves notes that link to the specified note.vault_forward_linksRetrieves notes that the specified note links to.vault_contextFinds semantically related notes using embeddings and link proximity.vault_relatedFinds structurally related notes based on shared neighbors.vault_hubsIdentifies the most connected notes in the vault.vault_orphansLists notes with no incoming or outgoing links.vault_attention_flowAnalyzes focus areas by grouping edits by tag or folder with trend detection.vault_topic_timelineTracks how a knowledge domain grows over time by bucketing edits.vault_note_historyRetrieves full edit history of a note including commits and metrics.vault_diffPerforms a structural diff of the vault over a specified number of days.vault_recentLists recently modified notes.vault_knowledge_velocityIdentifies which notes are being edited most frequently.vault_link_weightsCalculates link strength via co-edit frequency.vault_clustersPerforms community detection via label propagation.vault_concept_gapsIdentifies structural holes like missing notes or bridge gaps.vault_broken_linksFinds broken wikilinks with inferred topic tags.vault_maturityScores notes by development maturity based on word count and links.vault_prereq_treeGenerates a learning dependency tree from a root note.vault_statsProvides global metrics including note counts and tag distribution.vault_tagsLists tag frequency with example notes.vault_suggest_linksFinds semantically similar but unlinked note pairs.vault_batch_tagPreviews bulk tag operations.vault_open_questionsExtracts unresolved questions, TODOs, and unchecked checkboxes.Configuration
claude_desktop_config.json
{ "mcpServers": { "obsidian-emergent": { "command": "python", "args": ["/path/to/your/vault/.claude/server.py"] } } }Try it
→What are the most connected notes in my vault right now?
→Find semantically related notes to my current project note and suggest links.
→Show me the history of edits for my 'Project Alpha' note.
→Identify any broken links in my vault and suggest tags for them.
→What topics have I been focusing on the most over the last month?