vault-master-mcp

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.

Related MCP server: obsidian-codex-mcp

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:

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

Context Assembly

Write-Back

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

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