vault-mcp

Markdown + SQLite knowledge store with bidirectional [[wikilinks]], exposed as an MCP server. Designed for AI agents to maintain an interconnected knowledge base.

Installation

uvx vault-mcp                           # run directly without install
pip install vault-mcp                   # core (keyword search only)
pip install "vault-mcp[semantic]"       # + embedding-based semantic search

Running the MCP Server

# Start with default settings (vault in ./vault)
vault-mcp

# Custom vault directory
VAULT_DIR=/path/to/notes vault-mcp

# With semantic search enabled
VAULT_DIR=./vault VAULT_EMBEDDING_MODEL=jinaai/jina-embeddings-v5-text-nano vault-mcp

Environment Variables

Variable	Default	Description
VAULT_DIR	./vault	Root directory for markdown files
VAULT_EMBEDDING_MODEL	(none)	Sentence-transformers model name. Enables semantic search when set

Client Configuration

Claude Code

claude mcp add vault -- vault-mcp

Or .mcp.json:

{
  "mcpServers": {
    "vault": {
      "type": "stdio",
      "command": "vault-mcp",
      "env": { "VAULT_DIR": "./vault" }
    }
  }
}

Cursor / Windsurf / Other MCP Clients

Add to your MCP settings:

{
  "vault": {
    "command": "vault-mcp",
    "env": { "VAULT_DIR": "./vault" }
  }
}

Python Library (no MCP)

from vault_mcp import MarkdownVault, create_vault_tools

vault = MarkdownVault("./my-vault")
vault.write("skill/debugging", {"type": "skill", "confidence": "pattern"}, "# Debugging\n\n...")

# Or get all 11 tools as a dict of callables
tools = create_vault_tools(vault)
result = tools["vault_search"](query="debugging", mode="keyword")

Note Format

Each note is a .md file with YAML frontmatter, organized in type-based folders:

vault/
  skill/
    timeout-diagnosis.md
  concept/
    connection-pooling.md
  episodic/
    2024-01-15-incident.md

---
type: skill
tags: [database, timeout]
confidence: pattern
status: active
---

# Timeout Diagnosis

Description of the skill...

## Evidence
- [[episodic/2024-01-15-incident]]: First observed during outage

## Related
- [[concept/connection-pooling]]

Frontmatter Fields

Field	Required	Values
type	Yes	skill, episodic, concept, failure-pattern, system-knowledge
confidence	Yes	fact, pattern, heuristic
tags	No	Free-form string list
status	Auto	active, superseded, archived

Tools

Write & Edit

Tool	Description
vault_write(path, frontmatter, body)	Create or overwrite a note
vault_write_batch(entries)	Write multiple notes atomically
vault_edit(path, operation, params)	Incremental edit (4 operations below)
vault_delete(path)	Delete a note
vault_rename(old_path, new_path)	Rename + auto-rewrite all backlinks

Edit Operations

Operation	Params	Use
replace_string	{"old": "...", "new": "..."}	Inline corrections
set_frontmatter	{"confidence": "fact"}	Update metadata
replace_section	{"heading": "## Evidence", "body": "..."}	Rewrite a section
append_section	{"heading": "## Evidence", "content": "..."}	Append to a section

Read & Browse

Tool	Description
vault_read(path)	Read frontmatter + body
vault_list(path, depth, type_filter)	Browse directory

Search & Discovery

Tool	Description
vault_search(query, filters, mode, limit)	FTS5 / semantic / hybrid search
vault_backlinks(path)	Who links to this note
vault_traverse(start, depth, direction)	BFS graph traversal with directed edges
vault_lint()	Find dead links + orphan notes

Validation

Every write/edit automatically checks and returns warnings:

• Required frontmatter fields (type, confidence)
• Valid enum values
• H1 heading present in body
• All [[wikilinks]] resolve to existing notes

The write succeeds regardless — warnings are informational for the agent to decide whether to fix.

Architecture

.md files (source of truth, git-trackable)
    │
    ▼
.vault.db (SQLite index, auto-rebuilt if deleted)
    ├── notes       — YAML frontmatter metadata
    ├── notes_fts   — FTS5 full-text search
    ├── links       — [[wikilink]] directed graph
    ├── tags        — tag index
    └── notes_vec   — embedding vectors (optional)

License

MIT