markdown-vault-mcp

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. Results are short snippets; read fetches the whole section. See Embeddings.
• 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).
• Embeddings live in memory. Search by meaning holds every vector at 4 bytes × chunks × dimensions: about 70 MB for 23,000 chunks at 768 dimensions, about 900 MiB at ten times that and 1,024 dimensions. Memory, not query time, is the first limit (#1377).
• 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 of hundreds of thousands of chunks (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 and the summarize tool 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. 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.
MARKDOWN_VAULT_MCP_FILE_WATCHER	true	No	Watch the vault for external filesystem changes; auto-disabled when git pull is active or a webhook can deliver (HTTP/SSE transports only). Requires the file-watcher extra.
MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_BASE_URL	(none)	No	OpenAI-compatible endpoint base URL for the summarize tool; setting it enables the tool even without an API key. The bare OPENAI_BASE_URL routes traffic only when a key already enables the feature.

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

• Documentation and its llms.txt
• FastMCP and fastmcp-pvl-core, which this server is built on
• fastmcp-server-template, which generated this repository