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.
Headless semantic MCP server for Obsidian, Logseq, Dendron & any markdown vault. AST-based surgical editing, hybrid vector + TF-IDF search, zero-setup local embeddings — no app or plugins required. Stdio & SSE transport, Docker-ready.
星數
12
工具
—
可用率
—
💡 Why this server?
TL;DR — One npx command. No running app. No plugins. No vector DB. Semantic search works out of the box.
Differentiator
Details
🚫
No app or plugins required
Most Obsidian MCP servers (mcp-obsidian, obsidian-mcp-server) need Obsidian running with the Local REST API plugin. This server reads and writes .md files directly — point it at a folder and go.
🧠
Built-in semantic search, zero setup
Hybrid search: cosine-similarity vectors + TF-IDF + word proximity. Local embeddings (@huggingface/transformers, all-MiniLM-L6-v2, 384d) download on first run. No API keys, no external services. Ollama optional for higher quality.
🔬
Surgical AST-based editing
remark AST pipeline patches specific headings or block IDs without touching the rest of the file. Freeform line-range & string replace as fallback. Levenshtein fuzzy matching handles LLM typos.
🔓
Tool-agnostic
Obsidian vaults, Logseq graphs, Dendron workspaces, Foam, or any plain folder of .md files. If it's markdown, it works.
📦
Single package, no infrastructure
Unlike Python alternatives that need ChromaDB or other vector stores, everything runs in one Node.js process. npx @wirux/mcp-markdown-vault and you're running. Docker image available.
Server health, indexing info, vault structure overview, assisted overview rebuild
All tool responses include contextual hints based on the current workflow state.
💡 Operational Guidance
🛠️ Safe Editing
dryRun=true: Highly recommended before destructive operations like delete or replace with replaceMode="section".
Heading Disambiguation: If multiple identical headings are found, the server returns AMBIGUOUS_HEADING_TARGET with a list of candidates. Use blockId to target specific elements if headings are not unique.
AST vs Freeform: Always prefer AST operations (append, prepend, replace, delete) as they are structural. Use string_replace only as a last resort; it requires exact literal matches including whitespace and newlines.
replaceMode: replace defaults to body (preserves the heading, replaces content). Set replaceMode: "section" to replace the heading node and all its child headings.
returnContent: Set to section or file to 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 sequential view.read calls.
Workflow State: The workflow tool 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 a directory parameter 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. In dryRun=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.
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:
OLLAMA_URL set?
Ollama reachable?
Provider used
❌ No
—
🏠 Local (@huggingface/transformers, all-MiniLM-L6-v2, 384d)
✅ Yes
✅ Yes
🦙 Ollama (nomic-embed-text, 768d)
✅ Yes
❌ No
🏠 Local (fallback with warning)
No configuration needed for local embeddings — the model downloads on first use and is cached automatically.
⚙️ Configuration
Variable
Default
Description
VAULT_PATH
/vault
Markdown vault directory
VAULT_CONTEXT_MODE
assisted
Vault orientation mode: assisted (host LLM/agent calls prepare_overview to gather evidence, then generates prose and calls save_overview) or manual (you author meta/overview.md yourself and the server does not overwrite it). auto is a deprecated alias for assisted.
VAULT_CONTEXT
(deprecated)
Deprecated and ignored. Use VAULT_CONTEXT_MODE instead.
MCP_TRANSPORT_TYPE
stdio
stdio (single client) or sse (multi-client HTTP)
PORT
3000
HTTP port (SSE mode only)
OLLAMA_URL
(unset)
Set to enable Ollama embeddings
OLLAMA_MODEL
nomic-embed-text
Ollama embedding model name
OLLAMA_DIMENSIONS
768
Ollama embedding vector dimensions
VECTOR_STORE_URL
(unset)
Set to use Qdrant (e.g. http://localhost:6333). If unset, local persisted flat store is used.
VECTOR_STORE_COLLECTION
markdown_vault
Qdrant collection name when VECTOR_STORE_URL is set.
VECTOR_STORE_RESET
false
Set to true to auto-delete a mismatched vector index on startup and rebuild from scratch.
MCP_AUTH_TOKEN
(unset)
Bearer token for SSE transport auth. If set, all SSE endpoints require Authorization: Bearer <token>.
HOST_BIND_ADDRESS
127.0.0.1
Bind address for the SSE HTTP server.
BODY_LIMIT_BYTES
1mb
Max JSON request body size for SSE POST /messages.
Note: When using the default local vector store, a .markdown_vault_mcp directory 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.
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-overview MCP 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):
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 SafePath value object before any I/O
Headless semantic MCP server for Obsidian, Logseq, Dendron & any markdown vault. AST-based surgical editing, hybrid vector + TF-IDF search, zero-setup local embeddings — no app or plugins required. St