Submit
noambinabout-boop

vault-map

Community noambinabout-boop
Updated

A navigable map of your Obsidian vault for coding agents (MCP server): note skeletons, queryable frontmatter, situated content search - so agents stop reading whole notes to orient themselves. The markdown counterpart of repo-map.

vault-map

A navigable map of your Obsidian vault for coding agents (MCP server). Skeletons ofyour notes — headings with line ranges, queryable frontmatter, outgoing links — so theagent stops loading whole notes just to find its way around.

It is the markdown counterpart of repo-map(which does the same for source code).

Why

An agent that reads a 2 500-line note to answer one question burns ~49 000 tokens. Withoutline() + get_section() it reads the table of contents and the one chapter it needs:~5 200 tokens — an 89 % cut, measured on a real vault (python _smoke.py <vault>reproduces the measurement on yours).

The point isn't only cost: an agent that can afford to look around actually looks around,instead of answering from memory.

Tools

Tool What it gives you
vault_map() whole-vault map: folder, key frontmatter, H2 titles, outgoing links
outline(note) one note's heading tree with line numbers — call this before reading
get_section(note, title) the body of a single section, nothing else
query(filter) filter notes by frontmatter without opening them (status:draft, score>5)
grep_notes(pattern) regex search through note text, each hit located as note › section (Ln)
index(path) (re)target the server at another vault / folder of .md files

query also understands two pseudo-fields for finding a note by name: title:<word> andpath:<folder>.

Freshness is automatic: the map is rebuilt whenever a note changes (signature = aggregatedmtime + size), so an outline never lies. A stale outline is worse than an honest read.

Requirements

Python 3.10+. One dependency (mcp) — the engine itself is pure stdlib.

Install

git clone https://github.com/noambinabout-boop/vault-map.git
cd vault-map
python -m venv .venv
.venv/Scripts/pip install -r requirements.txt     # Windows
# .venv/bin/pip install -r requirements.txt       # macOS / Linux

Then register it with your agent. For Claude Code, from anywhere:

# Windows
claude mcp add vault-map --scope user -- C:\path\to\vault-map\.venv\Scripts\python.exe C:\path\to\vault-map\server.py

# macOS / Linux
claude mcp add vault-map --scope user -- /path/to/vault-map/.venv/bin/python /path/to/vault-map/server.py

Check with /mcp inside Claude Code. Any MCP-capable client works the same way — it is aplain stdio server: <python> server.py.

Point it at your vault

By default the server targets the current working directory. Two ways to change that:

  • Per call: index("/path/to/vault") — retargets on the fly.
  • Always the same vault, whatever project you launched the agent in: setVAULT_MAP_TARGET. In ~/.claude.json, on the server entry:
"vault-map": {
  "type": "stdio",
  "command": "C:\\path\\to\\vault-map\\.venv\\Scripts\\python.exe",
  "args": ["C:\\path\\to\\vault-map\\server.py"],
  "env": {
    "VAULT_MAP_TARGET": "C:\\path\\to\\your\\vault",
    "PYTHONIOENCODING": "utf-8"
  }
}

On Windows, PYTHONIOENCODING: utf-8 avoids a crash when a note contains an emoji.

Make the agent actually use it

Tools nobody calls save nothing. Put the reflex in your CLAUDE.md (or equivalent):

To find your way around the vault, use vault-map, not Read:
1. vault_map() for the big picture, query(filter) to filter by frontmatter
2. outline(note) before opening any note
3. get_section(note, title) to read only the part that matters
4. grep_notes(pattern) to search by content
Raw Grep/Read: last resort only.

If your client defers tool schemas, mark the server "alwaysLoad": true so the tools arethere from the first message.

Verify your install

python _handshake.py            # full MCP stdio round-trip
python _smoke.py <your-vault>   # builds the map and prints the token saving

License

MIT

MCP Server · Populars

MCP Server · New