markdown-vault-mcp

A generic markdown vault MCP server with FTS5 full-text search, semantic vector search, frontmatter-aware indexing, incremental reindexing, and non-markdown attachment support.

Documentation | PyPI | Docker

Point it at a directory of Markdown files (an Obsidian vault, a docs folder, a Zettelkasten, a PARA vault) and it exposes search, read, write, and edit tools over the Model Context Protocol.

Features

• Full-text search — SQLite FTS5 with BM25 scoring, porter stemming
• Semantic search — cosine similarity over embedding vectors (FastEmbed, Ollama, or OpenAI)
• Hybrid search — Reciprocal Rank Fusion combining FTS5 and vector results
• Diversity-aware ranking — each search result list caps a single document at 2 chunks (configurable), downweights chunks of long documents, and returns sentence-scale snippets — bounded LLM context cost per query, with full chunk recovery via read(path, section=heading)
• Adaptive heading-level chunking — long sections are recursively re-split at deeper heading levels (H1 → H6) until each chunk fits a configurable word budget, improving retrieval precision on synthesising essays without manual restructuring

Upgrading. As of this release, search returns query-relevant snippets in the content field by default (approximately 200 words). Pass snippet_words=0 to recover the prior full-chunk behaviour, or use read(path, section=heading) to fetch a specific chunk after seeing a snippet. Documents are also re-chunked on next reindex to honour the adaptive MARKDOWN_VAULT_MCP_MAX_CHUNK_WORDS threshold (default 400).

• Frontmatter-aware — indexes YAML frontmatter fields, supports required field enforcement
• Incremental reindexing — hash-based change detection, only re-processes modified files; an automatic boot-time reconciliation pass picks up changes made while no server was running, and the vector index converges to the reconciled chunk set (embedding exactly the delta)
• Write operations — create, edit, delete, rename documents with automatic index updates
• Attachment support — read, write, delete, and list non-markdown files (PDFs, images, etc.)
• Git integration — optional auto-commit and push on every write via GIT_ASKPASS
• OIDC authentication — optional token-based auth for HTTP deployments (Authelia, Keycloak, etc.)
• MCP tools — 31 LLM-visible tools including search, read, write, edit, delete, rename, git history, manual git sync, one-time transfer links, and admin operations; plus 6 app-only tools for MCP Apps clients
• MCP resources — 9 resources exposing vault configuration, statistics, tags, folders, document outlines, similar notes, recent notes, and an interactive SPA
• MCP prompts — 7 prompt templates including template-driven note creation

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, proposes meaningful connections, and writes 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.

No external scheduler, no separate capture app — the vault sits behind your conversations and absorbs their output.

Installation

From PyPI

pip install markdown-vault-mcp

With optional dependencies:

pip install markdown-vault-mcp[mcp]            # FastMCP server
pip install markdown-vault-mcp[embeddings-api]  # Ollama/OpenAI embeddings via HTTP
pip install markdown-vault-mcp[embeddings]      # FastEmbed local embeddings
pip install markdown-vault-mcp[all]             # MCP + FastEmbed + API embeddings

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

The Docker image uses [all] (MCP + FastEmbed + API embeddings). By default, semantic search works locally with FastEmbed and can switch to Ollama/OpenAI when configured. 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). See the systemd deployment guide for details.

Claude Desktop (.mcpb bundle)

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

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

Claude Desktop opens a GUI wizard that prompts for required env vars — no manual JSON editing needed. See Step 0 of the Claude Desktop guide for details.

Claude Code plugin

/plugin marketplace add pvliesdonk/claude-plugins
/plugin install markdown-vault-mcp@pvliesdonk

Installs the MCP server and the vault-workflow skill. See the Claude Code plugin guide for details.

Quick Start

As a library

from pathlib import Path
from markdown_vault_mcp import Vault

vault = Vault(source_dir=Path("/path/to/vault"))
vault.index.build_index()
results = vault.reader.search("query text", limit=10)

As an MCP server

export MARKDOWN_VAULT_MCP_SOURCE_DIR=/path/to/vault
markdown-vault-mcp serve

With Docker Compose

1. Copy an example env file:

   cp examples/obsidian-readonly.env .env

2. Edit .env to set MARKDOWN_VAULT_MCP_SOURCE_DIR to the absolute path of your vault on the host.

3. Start the service:

   docker compose up -d

4. Check the logs:

   docker compose logs -f markdown-vault-mcp

Example env files

For reverse proxy (Traefik) and deployment setup, see docs/deployment.md.

Server info

The server registers a built-in get_server_info tool (via fastmcp_pvl_core.register_server_info_tool) so operators can confirm the deployed version with a single MCP call. The response carries server_name, server_version, and core_version. Wire upstream version reporting (when applicable) inside the DOMAIN-UPSTREAM-START / DOMAIN-UPSTREAM-END sentinel in src/markdown_vault_mcp/server.py.

Configuration

All configuration is via environment variables with the MARKDOWN_VAULT_MCP_ prefix (except embedding provider settings, which use their own conventions).

Core

Server identity

Search and embeddings

Note: the chunker's character cap (MARKDOWN_VAULT_MCP_MAX_CHUNK_CHARS) is derived from the embedding model's context length, so changing the embedding model re-chunks the FTS index — not just the embeddings — and triggers an automatic cold rebuild of the index on the next startup. The defaults stay memory-light (BAAI/bge-small-en-v1.5 for FastEmbed, nomic-embed-text for Ollama); long-context models — nomic-ai/nomic-embed-text-v1.5 (8192 tokens) for FastEmbed, or bge-m3:latest for Ollama — are opt-in and need substantially more RAM/VRAM during indexing.

Git integration

Git integration has three modes:

• Managed mode (MARKDOWN_VAULT_MCP_GIT_REPO_URL set): server owns repo setup. On startup it clones into SOURCE_DIR when empty, or validates existing origin. Pull loop + auto-commit + deferred push are enabled.
• Unmanaged / commit-only mode (no GIT_REPO_URL): writes are committed to a local git repo if SOURCE_DIR is already a git checkout. No pull, no push.
• No-git mode: if SOURCE_DIR is not a git repo, git callbacks are no-ops.

When token auth is used (MARKDOWN_VAULT_MCP_GIT_TOKEN), remotes must be HTTPS. SSH remotes (for example [email protected]:owner/repo.git) are rejected with a startup error. Fix with: git -C /path/to/vault remote set-url origin https://github.com/owner/repo.git

Backward compatibility: MARKDOWN_VAULT_MCP_GIT_TOKEN without GIT_REPO_URL still works (legacy mode) but logs a deprecation warning.

File Watcher

Requires the watchdog optional extra: pip install 'markdown-vault-mcp[file-watcher]'. Automatically disabled when GIT_PULL_INTERVAL_S > 0 or GITHUB_WEBHOOK_SECRET is set.

Attachments

Non-markdown file support. See Attachments for details.

Bearer token authentication

Simple static token auth for HTTP deployments. Set a single env var — clients must send Authorization: Bearer <token>.

OIDC authentication

Full OAuth 2.1 authentication for HTTP deployments. OIDC activates when all four required variables are set. See Authentication for setup details.

Multi-auth: If both BEARER_TOKEN and all OIDC variables are set, the server accepts either credential — a valid bearer token or a valid OIDC session. This is useful when different clients use different auth flows (e.g. Claude web via OIDC and Claude Code via bearer token).

CLI Reference

markdown-vault-mcp <command> [options]

serve

Start the MCP server.

markdown-vault-mcp serve [--transport {stdio|sse|http}] [--host HOST] [--port PORT] [--http-path PATH]

Reverse Proxy Subpath Mounts

By default, HTTP transport serves MCP on /mcp. You can run it under a subpath:

markdown-vault-mcp serve --transport http --http-path /vault/mcp

Equivalent env-based config:

MARKDOWN_VAULT_MCP_HTTP_PATH=/vault/mcp

For reverse proxies, you can either:

• Keep app path at /mcp and use proxy rewrite/strip-prefix middleware.
• Set app path directly to the public path (/vault/mcp) and route without rewrite.

When OIDC is enabled under a subpath, the configuration is different: the subpath goes in BASE_URL only, and HTTP_PATH stays at /mcp. See OIDC subpath deployments.

Then your redirect URI is:

https://mcp.example.com/vault/auth/callback

index

Build the full-text search index.

markdown-vault-mcp index [--source-dir PATH] [--index-path PATH] [--force]

search

Search the vault from the CLI.

markdown-vault-mcp search <query> [-n LIMIT] [-m {keyword|semantic|hybrid}] [--folder PATH] [--json]

reindex

Incrementally reindex the vault (only processes changed files). When semantic search is configured, the vector index is converged to the updated chunk set — exactly the changed documents are re-embedded and orphaned vectors dropped, never the whole corpus.

markdown-vault-mcp reindex [--source-dir PATH] [--index-path PATH]

MCP Tools

Write tools (write, edit, delete, rename, fetch, git_sync, create_upload_link) are only available when MARKDOWN_VAULT_MCP_READ_ONLY=false. git_sync additionally requires managed git mode (MARKDOWN_VAULT_MCP_GIT_REPO_URL set).

browse_vault and show_context are LLM-visible in all clients; when called in an MCP Apps-capable client they open the interactive SPA. Six additional internal tools (vault_context, vault_list, vault_read, vault_search, vault_graph_neighborhood, vault_graph_hubs) use visibility="app" and are used by the SPA only — they are never visible to the LLM.

Resources

MCP resources expose vault metadata as structured JSON that clients can read directly without invoking tools.

Prompts

Prompt templates guide the LLM through multi-step workflows using the vault tools.

Write prompts (research, discuss, create_from_template, propose-links) are only available when MARKDOWN_VAULT_MCP_READ_ONLY=false.

Templates are regular markdown files. If placeholder template text pollutes search results, add your templates folder to MARKDOWN_VAULT_MCP_EXCLUDE (for example _templates/**).

User-defined prompts

Mount a directory of .md prompt files to override or extend the built-in prompts. Set MARKDOWN_VAULT_MCP_PROMPTS_FOLDER to the path. Each file's frontmatter defines description, arguments (a list of objects, each with name, description, and required fields), and optional tags. A user prompt with the same name as a built-in replaces it.

For a complete example — including Zettelkasten capture, development, and review prompts — see the Zettelkasten guide. For an alternative action-oriented workflow — Projects, Areas, Resources, Archive with triage, kickoff, and weekly review prompts — see the PARA guide.

MCP Apps

The server ships four browser-based views that MCP clients supporting the MCP Apps protocol can render inline or in fullscreen. They are delivered as a single HTML resource at ui://vault/app.html and registered using visibility="app" so they appear only in supporting clients and do not clutter the standard tool list. See the MCP Apps guide for details.

The two primary tools exposed to MCP Apps clients are:

Domain configuration: MCP Apps iframes are sandboxed to a specific Claude app domain. The domain is auto-computed from MARKDOWN_VAULT_MCP_BASE_URL. Override with MARKDOWN_VAULT_MCP_APP_DOMAIN if your deployment is hosted on a custom domain or behind a proxy that changes the apparent hostname.

Vendored dependencies (bundled at build time, no runtime CDN): vis-network (graph rendering), marked.js (markdown rendering), DOMPurify (XSS sanitization), ext-apps SDK (MCP Apps lifecycle).

One-Time Transfer Links

create_download_link and create_upload_link mint short-lived capability URLs so vault files can move to a browser or another service without inflating the LLM context window. The token embedded in the URL is the only credential — no Authorization header is required on the /transfer/{token} route.

# Download a vault file
create_download_link(path="reports/q1.pdf", ttl_seconds=600)
# → {"url": "https://mcp.example.com/transfer/<token>", ...}
curl "https://mcp.example.com/transfer/<token>" -o q1.pdf

# Upload a file to the vault
create_upload_link(path="assets/new-diagram.png")
# → {"url": "https://mcp.example.com/transfer/<token>", ...}
curl -X POST --data-binary @new-diagram.png "https://mcp.example.com/transfer/<token>"

Each token is consumed on its first successful use. A failed or interrupted transfer does not burn the token — retry is permitted until the TTL expires.

Requirements: HTTP or SSE transport; MARKDOWN_VAULT_MCP_BASE_URL set. See the transfer links guide for the full walkthrough and security model.

Attachments

In addition to Markdown notes, the server can read, write, delete, rename, and list non-markdown files (PDFs, images, spreadsheets, etc.). All existing tools are overloaded — no new tool names.

How it works

Path dispatch is extension-based: a path ending in .md is treated as a note; any other path is treated as an attachment if the extension is in the allowlist. The kind field on returned objects distinguishes the two: "note" or "attachment".

Reading attachments

read returns base64-encoded content for binary attachments:

{
  "path": "assets/diagram.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 12345,
  "content_base64": "<base64 string>",
  "modified_at": 1741564800.0
}

Writing attachments

write accepts a content_base64 parameter for binary content:

{ "path": "assets/diagram.pdf", "content_base64": "<base64 string>" }

Listing attachments

list_documents with include_attachments=true returns both notes and attachments:

[
  { "path": "notes/intro.md", "kind": "note", "title": "Intro", "folder": "notes", "frontmatter": {}, "modified_at": 1741564800.0 },
  { "path": "assets/diagram.pdf", "kind": "attachment", "folder": "assets", "mime_type": "application/pdf", "size_bytes": 12345, "modified_at": 1741564800.0 }
]

Default allowed extensions

pdf, docx, xlsx, pptx, odt, ods, odp, png, jpg, jpeg, gif, webp, svg, bmp, tiff, zip, tar, gz, mp3, mp4, wav, ogg, txt, csv, tsv, json, yaml, toml, xml, html, css, js, ts

Override with MARKDOWN_VAULT_MCP_ATTACHMENT_EXTENSIONS. Use * to allow all non-.md files.

Hidden directories: Attachments inside hidden directories (.git/, .obsidian/, .markdown_vault_mcp/, etc.) are never listed, regardless of extension settings. MARKDOWN_VAULT_MCP_EXCLUDE patterns are also applied to attachments.

Authentication

The server supports four auth modes:

1. Multi-auth — both bearer token and OIDC configured; either credential accepted (e.g. Claude web via OIDC + Claude Code via bearer token on the same instance)
2. Bearer token — set MARKDOWN_VAULT_MCP_BEARER_TOKEN to a secret string
3. OIDC — full OAuth 2.1 flow via OIDC_CONFIG_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, and BASE_URL
4. No auth — server accepts all connections (default)

Auth requires --transport http (or sse). It has no effect with --transport stdio.

For setup instructions, troubleshooting, and provider-specific guides, see the Authentication guide.

Development

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

# Run tests
uv run python -m pytest tests/ -x -q

# Lint and format
uv run ruff check src/ tests/
uv run ruff format src/ tests/

# Type check
uv run mypy src/ tests/

GitHub secrets

CI workflows reference three repository secrets. Configure them via Settings → Secrets and variables → Actions or with gh secret set:

GITHUB_TOKEN is auto-provided — no action needed.

Troubleshooting

Moving a scaffolded project

uv sync creates .venv/bin/* scripts with absolute shebangs pointing at the venv Python. If you move the repo (mv /old/path /new/path), uv run pytest fails with ModuleNotFoundError because the stale shebang resolves to a different interpreter than the venv's site-packages.

Fix:

rm -rf .venv
uv sync --all-extras --all-groups

uv run python -m pytest also works as a one-shot workaround.

uv.lock refresh after copier update

When copier update introduces new dependencies, CI runs uv sync --frozen which fails against a stale lockfile. Run uv lock locally and commit the refreshed uv.lock alongside accepting the copier-update PR.

Upgrading from earlier versions

• v2.0.0 (issue #469): search, get_similar, and get_context.similar now return grouped results. Each file appears once with a sections list; the flat content, heading, and score fields have moved inside each SectionHit. Library consumers must update iteration:

  # Before: result.content, result.heading
  # After:  result.sections[0].content, result.sections[0].heading

  MARKDOWN_VAULT_MCP_CHUNKS_PER_FILE replaces MARKDOWN_VAULT_MCP_CHUNKS_PER_DOC. SimilarItem is removed; use GroupedResult (also re-exported at the package level).

• MARKDOWN_VAULT_MCP_MAX_ATTACHMENT_SIZE_MB default lowered from 10 MB to 1 MB. Most LLM contexts can't survive a 10 MB base64-encoded attachment; the old default was a silent context-blow-up. If you have non-LLM consumers (scripts, CI) that need the old behaviour, set MARKDOWN_VAULT_MCP_MAX_ATTACHMENT_SIZE_MB=10 explicitly.

• MARKDOWN_VAULT_MCP_MAX_NOTE_READ_BYTES is a new env var (default 256 KB). Whole-document .md reads above this raise ValueError. Partial reads via read(path, section=heading) bypass the cap.

License

MIT