Markdown Vault MCP

[Markdown Vault MCP logo]

Markdown Vault MCP

[CI] [Quality Gate Status] [Coverage] [Reliability Rating] [Security Rating] [PyPI] [Python] [License] [Docker] [Docs] [llms.txt] [Template]

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.
• Hosted CLI reads. Search a running vault with markdown-vault-mcp search "term" --server https://vault.example/mcp; read notes, list metadata, collect context, traverse note links and discover paths with query path "topic" --fuzzy using the same connection options. Use query metadata, query body or query note for exact lexical pages, query count for the full matching population, and query aggregate --by tag for buckets. Use --json for native payloads or --agent for escaped records. See the CLI reference.
• Exact queries. Page through indexed notes, count every match, or group the full population with query_documents, count_documents and aggregate_documents. See Reader tools and the library API.
• Path discovery. Find literal paths or nearby ASCII spellings with search_paths; approximate coverage and output truncation are reported separately. See Reader tools.
• 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. A rename still accepts an etag that only the server's own link rewrites made stale. 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 1.25 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:

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