vault-master-mcp

Your Obsidian vault is a knowledge graph. Your AI should treat it like one.

The Problem

Every Obsidian MCP server gives your AI flat file access — read a note, list a folder, maybe search by name. But your vault isn't a folder of files. It's a knowledge graph of interconnected ideas linked by [[wikilinks]], tags, and frontmatter.

When an AI agent reads a single note without understanding its connections, it's like reading one page of a wiki and thinking you understand the topic.

vault-master-mcp builds an in-memory graph index from your vault's wikilinks, backlinks, and tags, then gives AI agents the tools to traverse, search, and assemble context from that graph — all within a token budget.

Key Features

Token-Budgeted Context Assembly

Ask for context on a topic and get the optimal subgraph that fits your token budget. No more "sorry, that's too much context" — the server handles it.

get_graph_context({ topic: "machine-learning", token_budget: 4000 })
→ Returns the most relevant connected notes that fit in 4K tokens

Graph Traversal

BFS walks with direction control. Follow only outgoing links, incoming backlinks, or both.

walk_graph({ start: "projects/my-project.md", depth: 2, direction: "outgoing" })
→ See everything this note links to, 2 levels deep

Knowledge Freshness Tracking

Notes carry lifecycle metadata — active, superseded, draft, archived. Agents can check if knowledge is current or chase fresher sources via superseded_by links.

Live Sync

Chokidar file watcher keeps the graph and search index updated as you edit in Obsidian. No restarts needed.

Full-Text Search with Graph Context

SQLite FTS5 search that optionally includes graph neighbors in results, so agents find notes and their connections.

Quick Start

npx vault-master-mcp --vault ~/my-vault

That's it. The server indexes your vault, starts the file watcher, and connects over stdio.

Or install globally:

npm install -g vault-master-mcp
vault-master-mcp --vault ~/my-vault

Works With

vault-master-mcp runs as an MCP server — it works with any MCP-compatible client:

| Client | Config Location | |--------|----------------| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | | Claude Code | ~/.claude/settings.json or project .mcp.json | | Cursor | Cursor MCP settings | | VS Code + Copilot | .vscode/mcp.json | | Any MCP client | See MCP docs |

Note on OpenClaw: OpenClaw does not currently support native MCP clients. The OpenClaw team considers direct MCP integration a "token tax" (tool definitions loaded into every agent session). The planned bridge is mcporter, which converts MCP servers into on-demand CLI commands — but this is not yet available. For multi-agent setups using OpenClaw, delegate vault discovery queries to a Claude Code session that has vault-master connected.

Claude Desktop Example

{
  "mcpServers": {
    "vault-master": {
      "command": "npx",
      "args": ["vault-master-mcp", "--vault", "/path/to/your/vault"]
    }
  }
}

Claude Code Example

{
  "mcpServers": {
    "vault-master": {
      "command": "npx",
      "args": ["vault-master-mcp", "--vault", "/path/to/your/vault"]
    }
  }
}

Tools (10)

Discovery

| Tool | Description | |------|-------------| | search_vault | Full-text search (FTS5) with optional graph neighbor expansion | | find_related | Find notes by graph proximity or tag — starts from a note and fans out | | list_notes | Browse vault by folder, tag, or frontmatter key |

Context Assembly

| Tool | Description | |------|-------------| | read_note | Read note with backlinks, freshness metadata, and graph degree | | get_graph_context | Token-budgeted subgraph assembly — the right amount of context, every time | | walk_graph | BFS traversal with direction control (outgoing / incoming / both) |

Write-Back

| Tool | Description | |------|-------------| | create_note | Create note with frontmatter and auto-linked [[wikilinks]] | | update_note | Update content or merge frontmatter into existing notes | | add_links | Add wikilinks between notes (creates Related section if absent) | | mark_superseded | Mark a note as replaced — updates freshness chain for agents |

Architecture

┌─────────────────────────────────────────────────┐
│                  MCP Client                      │
│         (Claude, Cursor, VS Code...)             │
└──────────────────┬──────────────────────────────┘
                   │ stdio (JSON-RPC)
┌──────────────────▼──────────────────────────────┐
│              vault-master-mcp                    │
│                                                  │
│  ┌─────────────┐  ┌──────────────────────────┐  │
│  │  Graph       │  │  SQLite + FTS5           │  │
│  │  Engine      │  │                          │  │
│  │              │  │  • Full-text search      │  │
│  │  • Adjacency │  │  • Metadata queries      │  │
│  │    index     │  │  • Frontmatter store     │  │
│  │  • BFS       │  │  • Link persistence      │  │
│  │  • Subgraph  │  │                          │  │
│  │    extraction│  └──────────────────────────┘  │
│  └─────────────┘                                 │
│                                                  │
│  ┌─────────────────────────────────────────────┐ │
│  │  Chokidar File Watcher                      │ │
│  │  • Incremental re-index on vault changes    │ │
│  └─────────────────────────────────────────────┘ │
└──────────────────┬──────────────────────────────┘
                   │ filesystem
┌──────────────────▼──────────────────────────────┐
│            Obsidian Vault (~/my-vault)            │
│                                                  │
│  notes.md ──[[wikilinks]]──► other-notes.md      │
│  #tags, frontmatter, folders                     │
└──────────────────────────────────────────────────┘

Dual-index design: The in-memory graph handles traversal and subgraph extraction at speed. SQLite with FTS5 handles full-text search and persistent metadata. Both stay in sync via the file watcher.

Freshness Model

Notes can carry optional frontmatter that agents use to assess knowledge currency:

---
status: active          # active | superseded | draft | archived
superseded_by: "[[new-approach.md]]"
last_verified: 2026-03-15
revision_of: "[[original-note.md]]"
---

When an agent reads a note via read_note, these fields are surfaced alongside backlink counts and graph degree — giving the agent enough signal to decide whether to trust the content or follow the superseded_by chain to fresher knowledge.

How It Compares

| Feature | vault-master-mcp | Typical Obsidian MCP | |---------|:---:|:---:| | Read/write notes | Yes | Yes | | Full-text search | FTS5 | Basic | | Graph traversal (BFS) | Yes | No | | Token-budgeted context | Yes | No | | Backlink awareness | Yes | Rarely | | Freshness tracking | Yes | No | | Live file watching | Yes | Rarely | | Directed link walking | Yes | No | | In-memory graph index | Yes | No |

Development

git clone https://github.com/mattbotcode/vault-master-mcp
cd vault-master-mcp
npm install
npm test        # 122 tests via Vitest
npm run build   # compile TypeScript

Tests run against a temporary in-memory vault fixture covering all 10 tools, graph traversal, FTS5 search, freshness tracking, and file watcher integration.

Contributing

Contributions are welcome! Whether it's:

Bug reports and feature requests via Issues
Pull requests for new tools, performance improvements, or bug fixes
Documentation improvements
Sharing your use cases

Please open an issue first for major changes so we can discuss the approach.

Roadmap

[ ] Semantic search via embeddings
[ ] Multi-vault support
[ ] Graph visualization endpoint
[ ] Plugin system for custom tools
[ ] Vault health/quality scoring

License

MIT

_{Built for the AI-native knowledge management era.}

MCP Servers