Vault Query

Vault Query

Give your assistant read access to a personal Markdown vault (Obsidian or plain .md files) through an MCP filesystem server, and let it actually find and surface what's in there. The hard-won part isn't the search call — it's the two failure modes below that make searches silently come back empty.

Setup

Run an MCP filesystem server scoped to your vault, e.g.:

# in your agent's MCP config
vault_filesystem:
  command: npx
  args: ["-y", "@modelcontextprotocol/server-filesystem", "<VAULT_PATH>"]

This exposes mcp_vault_filesystem_* tools (read/search/list). If your vault is a git clone kept fresh by a pull cron, see Step 0.

When to activate

The user asks about:

• Their notes, wiki, or anything they've documented
• Concepts, frameworks, protocols, references, sources
• People, places, or entities they track
• Their decision log, action items, priorities
• "What do I know about X?" / "Pull up my notes on Y"

How to query

Step 0 — Check freshness FIRST (if the vault is a git clone)

If the user writes to the vault from other machines, your local copy is only as fresh as the last pull. Before concluding something isn't there:

cd <VAULT_PATH> && git fetch origin && git log --oneline origin/main -5

If origin/main is ahead, pull before searching:

git pull --rebase origin main

This is the single most common cause of a false "I couldn't find it."

Step 1 — Locate files

mcp_vault_filesystem_search_files with a glob pattern (e.g. *labs*) and the vault path. ⚠️ This matches FILENAMES, not file contents.

Step 2 — Content search fallback

When the term lives inside a page (not in its filename), glob search misses it. Use grep:

grep -ril "keyword" <VAULT_PATH>/

Step 3 — Read + answer

mcp_vault_filesystem_read_file on the 2–3 most relevant hits, then answer in your own words from the content.

Always surface the actual findings. Deliver the specific entries / values / dates / names — don't just say "I found it." A lookup the user never sees the result of is worthless.

Pitfalls (the reason this skill exists)

• Stale cache is the #1 false-empty. Run the Step 0 git fetch every time the vault is a synced clone, not only when something looks missing.
• MCP glob search ≠ content search. search_files matches filename patterns only. For words inside files, use grep -ril.
• Filesystem search is case-sensitive on Linux. *Protocols* and *protocols* can return different results — prefer lowercase unless you know the casing.
• Don't over-read. On a broad hit, read the top 2–3 files, not everything.
• Mind privacy scope. Only point the MCP server at directories you intend the assistant to read; it can read everything in scope.