Search and index markdown vaults using full-text search (FTS5) and semantic embeddings, with frontmatter field indexing. For developers building knowledge bases, documentation systems, or note-taking integrations that need fast, accurate retrieval.
io.github.pvliesdonk/markdown-vault-mcp
Local install
STDIO
1 required env var
How models use it and what it is built for.
Search and index markdown vaults using full-text search (FTS5) and semantic embeddings, with frontmatter field indexing. For developers building knowledge bases, documentation systems, or note-taking integrations that need fast, accurate retrieval.
Local install — runs as a subprocess.
Configuration this server reads at startup.
Absolute path to the markdown vault directory
Disable write tools
Log level for FastMCP internals; app loggers default to INFO, -v overrides both to DEBUG
Event store backend for HTTP session persistence (file:///path or memory://)
MCP server name shown to clients
Directory for index and embeddings state files
Path to the FTS5 SQLite index file
Path to the numpy embeddings file
Comma-separated frontmatter fields to index for search
Comma-separated frontmatter fields required on every document
Comma-separated glob patterns to exclude from indexing
Embedding provider to use
OpenAI API key (required when MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDER=openai)
Ollama embedding model name
Force CPU-only inference for Ollama
Ollama server base URL
Git authentication token for push/pull
Remote git repository URL for managed mode
Git username for token auth
Git committer name
Git committer email
Seconds to wait before pushing (batches writes)
Enable Git LFS support
Seconds between periodic git pulls (0 to disable)
Comma-separated allowed attachment extensions, or * for all
Maximum attachment size in MB (0 for unlimited)
Folder name for note templates within the vault
Path to user-defined MCP prompt templates
Bearer token for authentication
OIDC auth mode: 'remote' (JWKS validation) or 'oidc-proxy' (OAuth proxy). Auto-detected if not set.
Public base URL of this server (required for OIDC)
OIDC discovery endpoint URL
OIDC client ID
OIDC client secret
Signing key for OIDC session JWTs (critical on Linux/Docker)
Expected OIDC token audience
Space-separated required OIDC scopes
Verify access token JWT instead of id_token
Override Claude app domain for MCP Apps iframe sandboxing
Path to the vault directory inside the container
Disable write tools
Log level for FastMCP internals; app loggers default to INFO, -v overrides both to DEBUG
Event store backend for HTTP session persistence (file:///path or memory://)
MCP server name shown to clients
Directory for index and embeddings state files
Path to the FTS5 SQLite index file
Path to the numpy embeddings file
Comma-separated frontmatter fields to index for search
Comma-separated frontmatter fields required on every document
Comma-separated glob patterns to exclude from indexing
Embedding provider to use
OpenAI API key (required when MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDER=openai)
Ollama embedding model name
Force CPU-only inference for Ollama
Ollama server base URL
Git authentication token for push/pull
Remote git repository URL for managed mode
Git username for token auth
Git committer name
Git committer email
Seconds to wait before pushing (batches writes)
Enable Git LFS support
Seconds between periodic git pulls (0 to disable)
Comma-separated allowed attachment extensions, or * for all
Maximum attachment size in MB (0 for unlimited)
Folder name for note templates within the vault
Path to user-defined MCP prompt templates
Run as this UID (Docker entrypoint)
Run as this GID (Docker entrypoint)
Bearer token for authentication
OIDC auth mode: 'remote' (JWKS validation) or 'oidc-proxy' (OAuth proxy). Auto-detected if not set.
Public base URL of this server (required for OIDC)
OIDC discovery endpoint URL
OIDC client ID
OIDC client secret
Signing key for OIDC session JWTs (critical on Linux/Docker)
Expected OIDC token audience
Space-separated required OIDC scopes
Verify access token JWT instead of id_token
Override Claude app domain for MCP Apps iframe sandboxing
Where to find authoritative docs and source for Markdown Vault.
Paste any of these into Agent Studio after connecting Markdown Vault.
Common questions about connecting and running Markdown Vault.
What search methods does this server support?
It supports full-text search (FTS5) for keyword queries and semantic search using embeddings. Both can be filtered by frontmatter fields you configure via MARKDOWN_VAULT_MCP_INDEXED_FIELDS.
How do I set up the markdown vault and point the server to it?
Set MARKDOWN_VAULT_MCP_SOURCE_DIR to the absolute path of your markdown directory. Optionally configure MARKDOWN_VAULT_MCP_STATE_PATH, MARKDOWN_VAULT_MCP_INDEX_PATH, and MARKDOWN_VAULT_MCP_EMBEDDINGS_PATH for index storage; defaults are created automatically.
Can I prevent the server from modifying my vault?
Yes, set MARKDOWN_VAULT_MCP_READ_ONLY=true to disable all write tools and make the server read-only.
How do I enforce required frontmatter fields across all documents?
Use MARKDOWN_VAULT_MCP_REQUIRED_FIELDS as a comma-separated list (e.g., author,date,status). The server will validate and report missing fields.
Does this server persist search state across sessions?
Yes, if you configure MARKDOWN_VAULT_MCP_EVENT_STORE_URL with a file:// or memory:// backend. Without it, state is ephemeral per session.
MCP Playground runs 10,000+ hosted MCP servers — GitHub, Linear, Notion, Stripe, Sentry and more — across Claude, GPT, Gemini, DeepSeek and 30+ AI models. Compare model answers side-by-side, save agent presets, share runs. Zero install.
Open Agent Studio