vault-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vault-mcp search for notes about connection pooling"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 searchRelated MCP server: LLM Wiki MCP
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-mcpEnvironment Variables
Variable | Default | Description |
|
| Root directory for markdown files |
| (none) | Sentence-transformers model name. Enables semantic search when set |
Client Configuration
Claude Code
claude mcp add vault -- vault-mcpOr .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 |
| Yes |
|
| Yes |
|
| No | Free-form string list |
| Auto |
|
Tools
Write & Edit
Tool | Description |
| Create or overwrite a note |
| Write multiple notes atomically |
| Incremental edit (4 operations below) |
| Delete a note |
| Rename + auto-rewrite all backlinks |
Edit Operations
Operation | Params | Use |
|
| Inline corrections |
|
| Update metadata |
|
| Rewrite a section |
|
| Append to a section |
Read & Browse
Tool | Description |
| Read frontmatter + body |
| Browse directory |
Search & Discovery
Tool | Description |
| FTS5 / semantic / hybrid search |
| Who links to this note |
| BFS graph traversal with directed edges |
| 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
Available Tools
11 toolsvault_backlinksA
Find all notes that contain a [[wikilink]] to the given path.
Args: path: Target note path.
Inputs: path (required). Returns: result
vault_deleteA
Delete a note and remove it from all indexes.
Args: path: Note path to delete.
Inputs: path (required). Returns: result
vault_editA
Apply an incremental edit to an existing note without rewriting the full content.
Args: path: Note path to edit. operation: One of "replace_string", "set_frontmatter", "replace_section", "append_section". params: Operation-specific parameters: - replace_string: {"old": "...", "new": "..."} - set_frontmatter: {"field": "value", ...} (merge update) - replace_section: {"heading": "## Section", "body": "new content"} - append_section: {"heading": "## Section", "content": "appended text"}
Returns warnings if the edit introduces structural issues.
Inputs: path (required), params (required), operation (required). Returns: result
vault_lintA
Check vault health: find dead [[wikilinks]] and orphan notes with no connections.
Inputs: no named parameters. Returns: result
vault_listA
Browse notes under a path.
Args: path: Directory path (e.g. "skill"). Use "" for vault root. depth: How many levels deep to list (default 1). type_filter: Only return notes of this type (e.g. "skill", "concept").
Inputs: path (required), depth, type_filter. Returns: result
vault_readA
Read a note from the vault. Returns its frontmatter and body.
Args: path: Note path (e.g. "concept/connection-pooling")
Inputs: path (required). Returns: result
vault_renameA
Rename or move a note. All [[backlinks]] in other notes are rewritten automatically.
Args: old_path: Current note path. new_path: New note path.
Inputs: new_path (required), old_path (required). Returns: result
vault_searchA
Search the vault by keyword, semantic similarity, or both.
Args: query: Search query text. filters: Optional filters: {"type": "skill", "confidence": "fact", "tags": ["db"]}. mode: "keyword" (FTS5), "semantic" (vector), or "hybrid" (both, default). limit: Max results (default 10).
Returns rich results with path, score, title, type, confidence, tags, and snippet.
Inputs: query (required), mode, limit, filters. Returns: result
vault_traverseA
Explore the link graph around a note via BFS traversal.
Args: start: Starting note path. depth: How many hops to follow (default 2). direction: "forward" (outgoing links), "backward" (incoming), or "both".
Returns nodes with depth and directed edges (source → target).
Inputs: start (required), depth, direction. Returns: result
vault_writeA
Create or overwrite a note in the vault.
Args: path: Note path relative to vault root (e.g. "skill/timeout-diagnosis") frontmatter: YAML metadata dict. Required fields: type, confidence. body: Markdown body content. Should start with "# Title".
Returns warnings if the note has structural issues.
Inputs: body (required), path (required), frontmatter (required). Returns: result
vault_write_batchA
Write multiple notes atomically in a single transaction.
Args: entries: List of dicts, each with "path", "frontmatter", "body" keys.
All notes are written together — if one fails, none are committed.
Inputs: entries (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Tools are mostly distinct with clear purposes, but vault_backlinks and vault_traverse (backward direction) both return incoming links, which could cause misselection. However, descriptions clarify the difference: backlinks is a direct lookup, while traverse explores the graph with depth.
All tools share the vault_ prefix, and most follow a verb pattern (write, read, edit, delete, list, search, lint, traverse). However, vault_backlinks and vault_write_batch deviate from the verb-only convention, making the set slightly inconsistent.
11 tools cover a complete note management workflow: CRUD, batch, search, list, lint, and graph exploration. The number is well-scoped, neither overwhelming nor thin.
The tool set provides full coverage of the vault lifecycle: create, read, update, delete, rename, batch operations, search, and health/link analysis. There are no obvious dead ends or missing core operations.
Maintenance
Related MCP Connectors
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Shared project wiki for AI agents: read and write pages, next actions, and activity logs over MCP.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceLocal-first knowledge base MCP server. Lets AI agents (Claude Code, Cursor, etc.) read and write your personal knowledge base through 20 MCP tools. Zero cloud dependency — all files stay on your machine.707MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for persistent, compounding markdown wikis maintained by LLMs. Enables incremental knowledge base building with interlinked pages, search, and raw source management.1MIT
- AlicenseAqualityCmaintenanceMCP server for managing a local, domain-agnostic knowledge base using Markdown notes with frontmatter. Enables AI agents to capture, read, search, link, and maintain notes with atomic writes and privacy controls.13MIT
- AlicenseAqualityBmaintenanceProvides AI agents with a local, private Markdown-based memory vault and SQLite search. Enables agents to search, read, list, and traverse linked knowledge pages via MCP with zero external runtime dependencies.733 PyPI9MIT