markdown-vault-mcp

markdown-vault-mcp

A generic markdown collection 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.

中文使用说明：本 fork 支持 OpenAI-compatible 向量接口。Claude Code、OpenCode、Codex、Cursor、Trae 的详细安装和配置方式见 中文配置指南。

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
• 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 — 30 LLM-visible tools including search, read, write, edit, delete, rename, git history, manual git sync, file-exchange uploads, 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 — 6 prompt templates including template-driven note creation

What you can do with it

With this server mounted in Claude, you can: