Markdown Vault MCP

Generic markdown vault MCP with hybrid search

Documentation | Config wizard | PyPI | Docker

Features

• Hybrid search: SQLite FTS5 keyword search (BM25, porter stemming) and semantic search (FastEmbed, Ollama, OpenAI, or Voyage AI embeddings, plus any OpenAI-compatible endpoint via OPENAI_BASE_URL), fused with Reciprocal Rank Fusion; diversity-aware ranking returns sentence-scale snippets with full-section recovery via read(path, section=heading). See the Embeddings guide, including the recipe for OpenAI-compatible endpoints.
• Frontmatter-aware indexing: YAML frontmatter fields become filterable and searchable, with optional required-field enforcement and adaptive heading-level chunking for long documents.
• Write operations: the write tools (write, edit, append, delete, rename, move_folder, fetch, git_sync, the okf_* tools, create_upload_link) are registered by default and hidden when MARKDOWN_VAULT_MCP_READ_ONLY=true; writes update the index automatically, per-folder _conventions.md authoring rules are surfaced to LLM clients at write time, and attachments (PDFs, images, and other non-markdown files) are read/write too.
• Incremental reindexing: hash-based change detection with boot-time reconciliation; the vector index converges to the reconciled chunk set, and parse-pipeline upgrades rebuild the index once automatically.
• Git integration: optional auto-commit (one commit per write tool call) with deferred push, plus a pull loop or a GitHub or GitLab push webhook for external changes; history and diff tools read the log back. An overwriting write returns the revision holding the content it replaced, and read(path, revision=sha) reads a note back at that revision, so an overwrite is recoverable from the client that made it. When the clone stops reaching its remote, every write result carries a remote warning saying the content is committed locally only, and the log marks the transition rather than repeating each cycle. See the Git integration guide.
• OKF-aware: recognizes Open Knowledge Format bundles and annotates results with each note's type, lifecycle status, staleness, and trust tier, plus conformance audit and migration tooling. See the OKF guide.
• MCP surface: 34 LLM-visible tools, 9 resources, and 8 prompt templates, plus browser-based MCP Apps views and one-time transfer links. Full references: Tools, Resources, Prompts, MCP Apps, Transfer links, CLI.

What you can do with it

With this server mounted in Claude, you can:

• Capture a URL as a note. "Fetch , summarize as a Resource note under 3-Resources/, and link any existing notes on the topic." Claude composes fetch + search + write.
• Research a topic into your vault. "Research product security regulations, compare them, and create a set of interlinked notes: one per regulation, plus a map-of-content." Claude composes web-search tools (client-side) + write with wikilinks. See the Research workflows guide for the full loop.
• Distill today's thinking. "Summarize today's conversations into Inbox notes." Claude.ai only; uses conversation_search + recent_chats + write. The para-capture-chats prompt is the one-click version.
• Find missing links. Fire the propose-links prompt from the + menu: it scans recently modified notes and proposes links between notes that aren't yet connected, writing them on confirmation.
• Split or merge captures. "Split this Inbox note into two." / "Merge this into <existing note> instead of duplicating." Claude composes read + write + delete.

The vault needs no external scheduler or separate capture app: it sits behind your conversations and absorbs their output.

Installation

From PyPI

pip install markdown-vault-mcp

If you add optional extras via the PROJECT-EXTRAS-START / PROJECT-EXTRAS-END sentinels in pyproject.toml, document them below:

pip install markdown-vault-mcp[mcp]             # FastMCP server
pip install markdown-vault-mcp[embeddings-api]  # Ollama/OpenAI embeddings via API
pip install markdown-vault-mcp[embeddings]      # FastEmbed local embeddings
pip install markdown-vault-mcp[file-watcher]    # watchdog-based external-change watcher
pip install markdown-vault-mcp[all]             # MCP + FastEmbed + API embeddings

For the Claude Code plugin channel (/plugin install markdown-vault-mcp@pvliesdonk) and all other install routes, see the Installation guide and the Claude Code plugin guide.

From source

git clone https://github.com/pvliesdonk/markdown-vault-mcp.git
cd markdown-vault-mcp
uv sync --all-extras --all-groups

Docker

docker pull ghcr.io/pvliesdonk/markdown-vault-mcp:latest

To run the newest merged code instead of the newest release, use the rolling edge tag. It is rebuilt on every merge to main and carries no version identity. See Image tags for the full tag list.

docker pull ghcr.io/pvliesdonk/markdown-vault-mcp:edge

A compose.yml ships at the repo root as a starting point. Copy .env.example to .env, edit, and docker compose up -d.

To attach a remote Python debugger (development only; the protocol is unauthenticated), see Remote debugging.

Linux packages (.deb / .rpm)

Download .deb or .rpm packages from the GitHub Releases page. Both install a hardened systemd unit; env configuration is sourced from /etc/markdown-vault-mcp/env (copy from the shipped /etc/markdown-vault-mcp/env.example).

Claude Desktop (.mcpb bundle)

Download the .mcpb bundle from the GitHub Releases page and double-click to install, or run:

mcpb install markdown-vault-mcp-<version>.mcpb

Claude Desktop prompts for required env vars via a GUI wizard, with no manual JSON editing needed.

For manual Claude Desktop configuration and setup options, see Claude Desktop deployment.

Release channels

Artifacts ship on three channels. Each row lists exactly what that channel publishes.