Markdown Vault MCP — Claude Code MCP server for your notes
Lets an agent search, read and write a folder of Markdown notes. An Obsidian vault works without changes.
claude mcp add --env MARKDOWN_VAULT_MCP_KV_STORE_URL=<MARKDOWN_VAULT_MCP_KV_STORE_URL> --env MARKDOWN_VAULT_MCP_TOOLS_ALLOW=<MARKDOWN_VAULT_MCP_TOOLS_ALLOW> --env MARKDOWN_VAULT_MCP_TOOLS_DENY=<MARKDOWN_VAULT_MCP_TOOLS_DENY> --env MARKDOWN_VAULT_MCP_SERVER_NAME=<MARKDOWN_VAULT_MCP_SERVER_NAME> --env MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION=<MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION> --transport stdio markdown-vault-mcp -- uvx markdown-vault-mcpWhat Markdown Vault MCP does
Point the server at a notes folder and your agent gets tools to read and write inside it. Search runs two ways: keyword matching through SQLite FTS5, and — once you set up an embedding provider — matching by meaning, with Reciprocal Rank Fusion merging the two. Vectors can live in files, SQLite or PostgreSQL. You get short snippets back; read pulls the full section.
YAML frontmatter fields turn into search filters, and long notes get split at their headings. Write tools (write, edit, append, delete, rename, move_folder, fetch, git_sync, the okf_* set, create_upload_link) ship enabled and disappear when MARKDOWN_VAULT_MCP_READ_ONLY=true. Overwriting a file needs the etag from the read that preceded it, and per-folder _conventions.md rules reach the client while it writes. Optional git support commits each write with a delayed push, plus pull or webhook sync, history and diffs.
One server handles one vault, so several vaults mean several instances, each with its own MARKDOWN_VAULT_MCP_SERVER_NAME. Only Markdown gets indexed — PDFs and images can be read or written as attachments, but their contents stay out of search. Embeddings sit in memory, so RAM runs out before query time does. Leave MARKDOWN_VAULT_MCP_INDEX_PATH unset and the index and change-tracking file stay in memory, rebuilt on every start.
What it helps with
- find a note by meaning instead of an exact word
- pull one section out of a long file
- write an edit back and get a git commit
- filter notes by frontmatter fields
- spot links in a note that do not resolve
Example prompts for the agent
- Search the vault for notes about deployment and show me the snippets
- Append a rollback section to
notes/deploy.mdand commit it - Which links in this note point nowhere?
How to install Markdown Vault MCP
Platform CLI
claude mcp add --env MARKDOWN_VAULT_MCP_KV_STORE_URL=<MARKDOWN_VAULT_MCP_KV_STORE_URL> --env MARKDOWN_VAULT_MCP_TOOLS_ALLOW=<MARKDOWN_VAULT_MCP_TOOLS_ALLOW> --env MARKDOWN_VAULT_MCP_TOOLS_DENY=<MARKDOWN_VAULT_MCP_TOOLS_DENY> --env MARKDOWN_VAULT_MCP_SERVER_NAME=<MARKDOWN_VAULT_MCP_SERVER_NAME> --env MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION=<MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION> --transport stdio markdown-vault-mcp -- uvx markdown-vault-mcpReplace <…> with your own values. 105 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from markdown-vault-mcp <command>
Platform CLI
codex mcp add markdown-vault-mcp --env MARKDOWN_VAULT_MCP_KV_STORE_URL=<MARKDOWN_VAULT_MCP_KV_STORE_URL> --env MARKDOWN_VAULT_MCP_TOOLS_ALLOW=<MARKDOWN_VAULT_MCP_TOOLS_ALLOW> --env MARKDOWN_VAULT_MCP_TOOLS_DENY=<MARKDOWN_VAULT_MCP_TOOLS_DENY> --env MARKDOWN_VAULT_MCP_SERVER_NAME=<MARKDOWN_VAULT_MCP_SERVER_NAME> --env MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION=<MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION> -- uvx markdown-vault-mcpReplace <…> with your own values. 105 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from markdown-vault-mcp <command>
Config file
{
"mcpServers": {
"markdown-vault-mcp": {
"command": "uvx",
"args": [
"markdown-vault-mcp"
],
"env": {
"MARKDOWN_VAULT_MCP_KV_STORE_URL": "<MARKDOWN_VAULT_MCP_KV_STORE_URL>",
"MARKDOWN_VAULT_MCP_TOOLS_ALLOW": "<MARKDOWN_VAULT_MCP_TOOLS_ALLOW>",
"MARKDOWN_VAULT_MCP_TOOLS_DENY": "<MARKDOWN_VAULT_MCP_TOOLS_DENY>",
"MARKDOWN_VAULT_MCP_SERVER_NAME": "<MARKDOWN_VAULT_MCP_SERVER_NAME>",
"MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION": "<MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION>"
}
}
}
}Replace <…> with your own values. 105 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from markdown-vault-mcp <command>
Config file
{
"servers": {
"markdown-vault-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"markdown-vault-mcp"
],
"env": {
"MARKDOWN_VAULT_MCP_KV_STORE_URL": "<MARKDOWN_VAULT_MCP_KV_STORE_URL>",
"MARKDOWN_VAULT_MCP_TOOLS_ALLOW": "<MARKDOWN_VAULT_MCP_TOOLS_ALLOW>",
"MARKDOWN_VAULT_MCP_TOOLS_DENY": "<MARKDOWN_VAULT_MCP_TOOLS_DENY>",
"MARKDOWN_VAULT_MCP_SERVER_NAME": "<MARKDOWN_VAULT_MCP_SERVER_NAME>",
"MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION": "<MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION>"
}
}
}
}Replace <…> with your own values. 105 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from markdown-vault-mcp <command>
Platform CLI
gemini mcp add -e MARKDOWN_VAULT_MCP_KV_STORE_URL=<MARKDOWN_VAULT_MCP_KV_STORE_URL> -e MARKDOWN_VAULT_MCP_TOOLS_ALLOW=<MARKDOWN_VAULT_MCP_TOOLS_ALLOW> -e MARKDOWN_VAULT_MCP_TOOLS_DENY=<MARKDOWN_VAULT_MCP_TOOLS_DENY> -e MARKDOWN_VAULT_MCP_SERVER_NAME=<MARKDOWN_VAULT_MCP_SERVER_NAME> -e MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION=<MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION> markdown-vault-mcp uvx markdown-vault-mcpReplace <…> with your own values. 105 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from markdown-vault-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Markdown Vault MCP
How do I install Markdown Vault MCP in Claude Code?
Run `claude mcp add --env MARKDOWN_VAULT_MCP_KV_STORE_URL=<MARKDOWN_VAULT_MCP_KV_STORE_URL> --env MARKDOWN_VAULT_MCP_TOOLS_ALLOW=<MARKDOWN_VAULT_MCP_TOOLS_ALLOW> --env MARKDOWN_VAULT_MCP_TOOLS_DENY=<MARKDOWN_VAULT_MCP_TOOLS_DENY> --env MARKDOWN_VAULT_MCP_SERVER_NAME=<MARKDOWN_VAULT_MCP_SERVER_NAME> --env MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION=<MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION> --transport stdio markdown-vault-mcp -- uvx markdown-vault-mcp`.
What does Markdown Vault MCP do?
It gives an agent access to a Markdown notes folder: keyword and semantic search, section reads, file writes and edits, link handling, and optional git commits.
Can one server cover several vaults?
No. Each vault needs its own server instance, and each instance gets a distinct MARKDOWN_VAULT_MCP_SERVER_NAME.
