vault-master-mcp

<p align="center"> <h1 align="center">vault-master-mcp</h1> <p align="center"> <strong>Your Obsidian vault is a knowledge graph. Your AI should treat it like one.</strong> </p> <p align="center"> <a href="https://www.npmjs.com/package/vault-master-mcp"><img src="https://img.shields.io/npm/v/vault-master-mcp.svg" alt="npm version"></a> <a href="https://github.com/mattbotcode/vault-master-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a> <img src="https://img.shields.io/badge/tests-122%20passing-brightgreen.svg" alt="Tests"> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-purple.svg" alt="MCP Compatible"></a> </p> </p>

---

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

---

<p align="center"> _{Built for the AI-native knowledge management era.} </p>