Markdown Vault MCP
Generic markdown vault MCP with hybrid search
Documentation | Config wizard | PyPI | Docker
Give Claude, or any MCP client, a folder of Markdown notes to search, read and write. An Obsidian vault works as it is.
- Hybrid search. Keyword search with SQLite FTS5 and, once an embedding provider is configured, search by meaning, fused by Reciprocal Rank Fusion, with the vectors kept in SQLite, files or PostgreSQL. Results are short snippets;
read fetches the whole section. See Embeddings and Choosing an embedding store.
- Frontmatter as data. YAML frontmatter fields become search filters, and long notes are split at their headings.
- Careful writes. The write tools (
write, edit, append, delete, rename, move_folder, fetch, git_sync, the okf_* tools, create_upload_link) are on by default and hidden when MARKDOWN_VAULT_MCP_READ_ONLY=true. Replacing a file takes the etag from reading it, and per-folder _conventions.md rules reach the client as it writes.
- Git. Optional commit per write with a delayed push, pull or webhook sync, and history and diffs; an overwritten note can be read back at the revision it replaced. See Git integration.
- Links. Backlinks, outlinks, broken links and the path between two notes, for wikilinks and Markdown links alike, with interactive views in clients that render MCP Apps. With
MARKDOWN_VAULT_MCP_REPORT_UNRESOLVED_LINKS=true, write, edit and append name each link they added that doesn't resolve.
- Open Knowledge Format. OKF bundles are recognized, and results carry each note's type, status and trust tier. See OKF.
The tools reference lists every tool. The same engine is a Python library: see the Vault API.
Does it fit?
What the server can reach, what it changes and who gets in is set out in the security model; the block below says who it serves and where it stops.
It suits one person or a small team who keep notes as Markdown files and want Claude to search them, follow their links and write back into them, on their own machine or as a shared server. It reaches the vault folder, plus only what you configure: a git remote, an embedding or summarizing model, and the URLs a fetch call names.
What it assumes:
- One vault per server. Several vaults take one server each, for now (#1232); give each a
MARKDOWN_VAULT_MCP_SERVER_NAME.
- Markdown is what gets searched. Other files, such as PDFs and images, can be read and written as attachments, but their contents are not indexed yet (#1234).
- The default store trades search speed for memory. With an index path the vectors live in a SQLite database and each search reads them from it: measured with 227,640 sections at 1,024 dimensions, searching added 25 MB to the server and 95 in 100 searches returned within about a second. Holding them in memory (the
numpy store) answered those searches about ten times faster, and peaked at about 2.1 GB while searching. Choosing an embedding store has the measured costs and the limits.
- State sits on local disk. The index and embeddings are files, and the change-tracking file sits beside the index, never inside the vault. Without
MARKDOWN_VAULT_MCP_INDEX_PATH, the index and that file stay in memory and are rebuilt at each start.
Reach for something else for a corpus beyond the 227,640 sections it was measured at (a vector database behind a retrieval pipeline), for mostly scanned or office documents (a document management system with text recognition), or for many users who must not see each other's notes (a multi-tenant knowledge platform): every caller the server admits gets every tool it exposes.
Quick start
Pick the client you use. Each line installs the released version; the Get started tutorials carry on from there.
Claude Desktop. Download the .mcpb bundle from the releases page and open it with Claude Desktop (or Settings › Extensions › Advanced settings › Install Extension…). Claude Desktop asks for the required settings itself. Tutorial.
Claude Code. Two commands inside Claude Code; the second asks for a scope. Tutorial.
/plugin marketplace add pvliesdonk/claude-plugins
/plugin install markdown-vault-mcp@pvliesdonk
A client that runs a command (stdio). To register it in Claude Code, see the Claude Code tutorial.
uv tool install "markdown-vault-mcp"
markdown-vault-mcp serve
A server for remote clients (streamable HTTP). A remote server connects the clients.
docker run --rm -p 8000:8000 --env-file .env ghcr.io/pvliesdonk/markdown-vault-mcp:latest
A compose.yml ships at the repository root and runs as-is: copy .env.example to .env, then docker compose up -d. Deploy covers authentication, OIDC, a reverse proxy and system packages (.deb/.rpm on the releases page). The server answers /health and /health/ready outside the MCP mount, and its get_server_info tool reports the running version.
The plain package covers keyword search, the write tools and git. Search by meaning, the file watcher, the summarize tool and keeping embeddings in PostgreSQL need extras; [all] installs every one:
uv tool install "markdown-vault-mcp[all]"
The Docker image, the .mcpb bundle and the Claude Code plugin already include them. Installation lists each extra.
Configuration
Everything is configured through environment variables with the MARKDOWN_VAULT_MCP_ prefix. The ones most installs set:
| Variable | Default | Required | Description |
|---|
MARKDOWN_VAULT_MCP_SOURCE_DIR | /data/vault | No | Path to the markdown vault directory. When it does not exist, or the server cannot access it, the server starts but every tool fails with a message saying which until it is fixed (managed git mode clones into it). Symbolic links inside the vault are followed on Python 3.13+. |
MARKDOWN_VAULT_MCP_READ_ONLY | false | No | Set to true to hide the write tools (write, edit, append, delete, rename, move_folder, fetch, git_sync, the okf_* tools, create_upload_link) and serve a search-only vault. |
MARKDOWN_VAULT_MCP_WRITE_PROTECT_EXISTING | true | No | Refuse a write that would overwrite an existing file when no if_match etag is supplied. Deliberate replacement still works: read the file first, then pass if_match. Unaffected: edit, append, delete, rename. Set to false to allow blind overwrites. |
MARKDOWN_VAULT_MCP_REPORT_UNRESOLVED_LINKS | false | No | Set to true to have write, edit and append list, under unresolved_links, the target of each link the call added that get_broken_links reports. Links the note already held are left out. Off by default, leaving those responses unchanged. |
MARKDOWN_VAULT_MCP_DEFAULT_SEARCH_MODE | auto | No | Mode used when a search call omits 'mode': auto, keyword, semantic, or hybrid. The default 'auto' picks hybrid when embeddings are configured and keyword when they are not. Pin 'keyword' to keep unqualified searches off the embedding provider (each hybrid or semantic search embeds the query, which costs an API call on a metered provider). A configured semantic/hybrid default also degrades to keyword without embeddings, so no setting can make a vault unsearchable; an explicit mode= argument is never downgraded. |
MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDER | (none) | No | Embedding provider: openai, voyage, ollama, or fastembed; setting it turns on search by meaning. Unset auto-detects from the environment (never voyage), but only when EMBEDDINGS_PATH is set or EMBEDDING_STORE=postgres. Any OpenAI-compatible endpoint works with openai plus OPENAI_BASE_URL; see the embeddings guide. |
MARKDOWN_VAULT_MCP_GIT_REPO_URL | (none) | No | HTTPS remote URL for managed git mode: the server clones into an empty SOURCE_DIR on startup (or validates an existing origin) and enables the pull loop, auto-commit, and deferred push. |
Every variable the server reads, the shared ones included, is in the configuration reference; .env.example lists the same surface in copy-paste form, and the config wizard writes one for your deployment.
Documentation
- Security model: what the server can reach, what it changes and who gets in.
- Get started: a first success with your client.
- Deploy: Docker, authentication, OIDC, reverse proxy.
- Use: the features, for real tasks.
- Reference: configuration, tools, resources, prompts, command line.
- Upgrade: release channels, and what an upgrade changes for your clients and your data.
- Contribute: local development, secrets, where a fix belongs;
CONTRIBUTING.md and SECURITY.md at the root.
Design decisions
- Document identity is the relative path with
.md extension; frontmatter is optional by default (REQUIRED_FIELDS opts into enforcement).
- Hybrid search uses Reciprocal Rank Fusion over the FTS5 and vector result lists, with diversity-aware ranking capping chunks per document.
- Tool semantics mirror Claude Code's Read/Write/Edit patterns, so LLM clients drive the vault with habits they already have.
- The library is synchronous; the MCP layer wraps calls in
asyncio.to_thread(). File writes return after saving, while index updates run in the background. Index-dependent mutations wait for prior writes; see index freshness.
- Indexing is hash-based: unchanged files are never re-parsed, and any change to how stored rows derive from a note's bytes bumps
INDEX_SEMANTICS_VERSION so deployed vaults rebuild themselves once on upgrade.
The full decision log lives in the design document.
Links
