📁 Markdown Vault MCP Server
Headless semantic MCP server for Obsidian, Logseq, Dendron, Foam, and any folder of markdown files.
npm install and point it at a folder. Hybrid search, AST editing, zero-config embeddings. No app, no plugins, no API keys.
💡 Why this server?
TL;DR — One
npxcommand. No running app. No plugins. No vector DB. Semantic search works out of the box.
💎 Obsidian · 📓 Logseq · 🌳 Dendron · 🫧 Foam · 📂 Any .md folder
✨ Features
🛠️ MCP Tools
All tool responses include contextual hints based on the current workflow state.
💡 Operational Guidance
🛠️ Safe Editing
dryRun=true: Highly recommended before destructive operations likedeleteorreplacewithreplaceMode="section".- Heading Disambiguation: If multiple identical headings are found, the server returns
AMBIGUOUS_HEADING_TARGETwith a list of candidates. UseblockIdto target specific elements if headings are not unique. - AST vs Freeform: Always prefer AST operations (
append,prepend,replace,delete) as they are structural. Usestring_replaceonly as a last resort; it requires exact literal matches including whitespace and newlines. replaceMode:replacedefaults tobody(preserves the heading, replaces content). SetreplaceMode: "section"to replace the heading node and all its child headings.returnContent: Set tosectionorfileto see the results of your edit immediately in the tool response (max 8KB).
🚀 Performance & Consistency
bulk_read: Use this to read 2 or more files/sections concurrently. It is significantly faster than multiple sequentialview.readcalls.- Workflow State: The
workflowtool manages session-specific state used for contextual hints. It does not modify vault data or search indexes. system.reindex: Only use this for recovery or after making out-of-band file changes (e.g., via external scripts). Normal MCP edits automatically update backlinks and queue vector indexing.view.outline: Supports adirectoryparameter to get a flat list of headings across multiple files in a folder.
🧪 Batch Edits
- Sequential Execution: Operations in a batch are executed one by one. If one fails, the remaining are skipped.
- Dry-run Asymmetry: In
dryRun=false, each operation sees the file state after previous operations. IndryRun=true, the file is never written, so sequential dependent operations (e.g., editing the same line twice) may produce different results than a live run.
🚀 Quick Start
Prerequisites
📦 Install from NPM
npm install -g @wirux/mcp-markdown-vault
Then run directly:
VAULT_PATH=/path/to/your/vault markdown-vault-mcp
🔌 MCP Client Configuration
Add to your MCP client config (e.g. Claude Desktop, Claude Code):
{
"mcpServers": {
"markdown-vault": {
"command": "npx",
"args": ["-y", "@wirux/mcp-markdown-vault"],
"env": {
"VAULT_PATH": "/path/to/your/vault"
}
}
}
}
npx -yauto-installs the package if not already present — no global install needed.
Try it in the browser: You can test this server directly at Glama Inspector — no local install required.
🐳 Docker
Pull the pre-built multi-arch image from GitHub Container Registry:
docker pull ghcr.io/wirux/mcp-markdown-vault:latest
Or use Docker Compose:
docker compose up
Edit docker-compose.yml to point at your markdown vault directory. The default compose file uses SSE transport on port 3000.
🛠️ Development (from source)
git clone https://github.com/wirux/mcp-markdown-vault.git
cd mcp-markdown-vault
npm install
npm run build
VAULT_PATH=/path/to/your/vault node dist/index.js
🌐 Transport Modes
SSE starts an HTTP server on PORT (default 3000):
GET /sse— establishes an SSE stream (one per client)POST /messages?sessionId=...— receives JSON-RPC messages
MCP_TRANSPORT_TYPE=sse PORT=3000 VAULT_PATH=/path/to/vault npx @wirux/mcp-markdown-vault
Each SSE client gets its own workflow state. Shared resources (vault, vector index, embedder) are reused across all connections.
🧠 Embedding Providers
The server selects an embedding provider automatically:
No configuration needed for local embeddings — the model downloads on first use and is cached automatically.
⚙️ Configuration
Note: When using the default local vector store, a
.markdown_vault_mcpdirectory will be created in your vault. It's recommended to add this directory to your.gitignore.
Use assisted mode when you want the connected host LLM/agent to generate and refresh vault context from server-provided evidence. Use manual mode when you want to write and maintain meta/overview.md yourself; in manual mode, the server creates the file if missing but does not overwrite it.
🏗️ Architecture
Clean Architecture with strict layer separation:
src/
├── domain/ 🔷 Errors, interfaces (ports), value objects
├── use-cases/ 🔶 Business logic (AST, chunking, search, workflow)
├── infrastructure/ 🟢 Adapters (file system, Ollama, vector store)
└── presentation/ 🟣 MCP tool bindings, transport layer (stdio/SSE)
See CLAUDE.md for detailed architecture docs and CHANGELOG.md for implementation history.
🗺️ Self-Orienting Context Layer
Connected agents automatically discover when to query this vault and how to use its tools — no explicit user instructions needed.
Quick start: Run the
rebuild-overviewMCP prompt after adding notes to your vault. This generates context that helps agents route queries to the right vault.
How it works
The server delivers vault context through multiple mechanisms (graceful degradation across clients):
Modes
To rebuild in assisted mode: invoke the rebuild-overview MCP prompt, or ask your agent to call system.prepare_overview then system.save_overview.
Vault meta files
On first startup, the server creates two files in <VAULT_PATH>/meta/:
Tip: Keep
vault_scopeshort and specific — it tells MCP hosts what information this vault can answer.
🚢 CI/CD & Release
Fully automated via GitHub Actions and Semantic Release:
- Versioning follows Conventional Commits —
feat:= minor,fix:= patch,feat!:/BREAKING CHANGE:= major - Docker images are built for
linux/amd64andlinux/arm64via QEMU - NPM package published as
@wirux/mcp-markdown-vault - Docker image available at
ghcr.io/wirux/mcp-markdown-vault
🧪 Testing
568 tests across 49 files, written test-first (TDD).
npm test # Run all tests
npx vitest run src/use-cases/ast-patcher.test.ts # Single file
npm run test:watch # Watch mode
npm run test:coverage # Coverage report
Tests use real temp directories for file system operations and in-memory MCP transport for integration tests. No external services required.
🔒 Security
- 🛡️ All file paths validated through
SafePathvalue object before any I/O - 🚫 Blocks path traversal:
../, URL-encoded (%2e%2e), double-encoded (%252e), backslash, null bytes - ✍️ Atomic file writes (temp file + rename) prevent partial writes
- 👤 Docker container runs as non-root user
