Skip to content

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.

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
  • Frontmatter-aware: indexes YAML frontmatter fields, supports required field enforcement
  • Incremental reindexing: hash-based change detection, only re-processes modified files
  • Write operations: create, edit, append to, delete, rename documents with automatic index updates
  • Folder conventions: per-folder _conventions.md files carry your authoring rules, surfaced to LLM clients at write time via get_conventions and in write/edit results
  • Open Knowledge Format: recognizes OKF bundles (an okf_version declaration in the root index.md) and annotates search/read results with each note's type, lifecycle status, staleness, and trust tier; those dimensions are filterable and nudge ranking, and the server ships an okf_validate audit, one-shot migration transforms, an optional enforced write layer (provenance + verification + log.md/index.md upkeep), and a downloadable bundle export
  • Attachment support: read, write, delete, and list non-markdown files (PDFs, images, and so on)
  • LLM summarization: optional summarize tool condenses a note, a set of notes, or a subtree with a language model via any OpenAI-compatible endpoint (OpenAI, Ollama, Anthropic, vLLM, and others); the synthesis references the individual source notes by path. Gated on OPENAI_API_KEY or a configured base URL.
  • Git integration: optional auto-commit and push on every write via GIT_ASKPASS
  • OIDC authentication: optional token-based auth for HTTP deployments
  • MCP tools: search, read, write, edit, append, delete, rename, link graph analysis, and admin operations
  • MCP resources: vault configuration, statistics, tags, folders, document outlines, similar notes, and recent notes
  • MCP prompts: summarize, research, discuss, create from template, compare, and find related notes
  • MCP Apps: browser-based views (Context Card, Graph Explorer, Vault Browser, and Note Preview) for clients supporting the MCP Apps protocol
  • One-time transfer links: mint short-lived capability URLs to move files into or out of the vault out-of-band over HTTP (create_download_link / create_upload_link; HTTP/SSE transports only)
  • Configuration Generator: build a working config, Docker command, or systemd unit in your browser.

What you can do with it

A few flows the server enables with an LLM on top (none of these require a bespoke prompt):

  • "Fetch and summarize into a Resource note." Claude composes fetch + search + write.
  • "Research and create a set of interlinked notes." Claude composes web tools + write with wikilinks. See the Research workflows guide for the full loop.
  • "Summarize today's conversations into Inbox notes." Claude.ai composes conversation_search + recent_chats + write; the para-capture-chats prompt is the one-click version.
  • Find missing links. The propose-links builtin prompt scans recently modified notes and proposes useful connections.

See MCP Prompts for the codified workflows and the ambient-pattern reference.

Release notes

Per-minor release notes explain what changed in each release, who is affected, and what to check before upgrading. The GitHub release body links to the matching page.

Quick Start

As a library

from pathlib import Path
from markdown_vault_mcp.vault 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

cp examples/obsidian-readonly.env .env
# Edit .env to set MARKDOWN_VAULT_MCP_SOURCE_DIR
docker compose up -d

As a Claude Code plugin

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

See Installation for all installation methods (PyPI, uv, Docker, Linux packages, Claude Code plugin) and Configuration for all available options.

Architecture

The library is fully synchronous, with no asyncio in core modules. The MCP server layer uses asyncio.to_thread() to bridge to the async FastMCP layer.

┌──────────────┐
│  MCP Server   │  ← FastMCP, asyncio.to_thread()
├──────────────┤
│  Vault        │  ← Thin facade / public API
├──────────────┤
│  Scanner      │  ← File discovery, frontmatter parsing, chunking
│  FTS Index    │  ← SQLite FTS5, BM25 scoring
│  Vector Index │  ← numpy embeddings, cosine similarity
│  Tracker      │  ← Hash-based change detection
│  Providers    │  ← Embedding provider ABC + implementations
│  Git          │  ← Auto-commit/push strategy
├──────────────┤
│  Config       │  ← Environment variable loading
└──────────────┘

License

MIT