📁 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.

👁 CI / Release
👁 PR Check
👁 npm version
👁 Docker
👁 License: MIT
👁 TypeScript
👁 Node.js
👁 Tests
👁 mcp-markdown-vault MCP server

👁 Markdown Vault MCP Server Demo

💡 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.

💎 Obsidian · 📓 Logseq · 🌳 Dendron · 🫧 Foam · 📂 Any .md folder

✨ Features

Feature	Description
🗂️	Headless vault ops	Read, create, update, edit, delete `.md` notes with strict path traversal protection
📑	Read by heading	Read a single section by heading title — returns only content under that heading (up to the next same-level heading), saving context window space
📦	Bulk read	Read multiple files and/or heading-scoped sections in a single call — reduces MCP round-trips with per-item fault tolerance
🔬	Surgical editing	AST-based patching targets specific headings or block IDs — never overwrites the whole file
🔍	Fragment retrieval	Heading-aware chunking + TF-IDF + proximity scoring returns only relevant sections
📂	Scoped search	Optional directory filter for `global_search` and `semantic_search` — restrict results to specific folders to reduce noise
🧠	Semantic search	Hybrid vector + lexical search with background auto-indexing
⚡	Zero-setup embeddings	Built-in local embeddings via `@huggingface/transformers` — Ollama optional
🔄	Workflow tracking	Petri net state machine with contextual LLM hints
🌐	Dual transport	Stdio (single client) or SSE over HTTP (multi-client, Docker-friendly)
✏️	Freeform editing	Line-range replacement and string find/replace as AST fallback
🏷️	Frontmatter management	AST-based read and update of YAML frontmatter — safely manage tags, statuses, and metadata without corrupting file structure
👀	Dry-run / diff preview	Preview any edit operation as a unified diff without saving — set `dryRun=true` on any edit action
📝	Templating / scaffolding	Create new notes from template files with `{{variable}}` placeholder injection — refuses to overwrite existing files
🗺️	Self-orienting vault context	Assisted or manual `meta/overview.md` with host-visible `vault_scope` and live `vault://overview` context for connected agents
📦	Batch edit	Apply multiple edit operations in a single call — sequential execution, stops on first error, supports `dryRun`, max 50 ops
🔗	Backlinks index	Find all notes linking to a given path — supports wikilinks and markdown links with line numbers and context snippets
🎯	Typo resilience	Levenshtein-based fuzzy matching for edit operations

🛠️ MCP Tools

Tool	Actions	Description
📁 vault	`list` `read` `create` `update` `delete` `stat` `create_from_template`	Full CRUD for vault notes + template scaffolding
✏️ edit	`append` `prepend` `replace` `delete` `line_replace` `string_replace` `frontmatter_set` + `operations[]` batch mode	AST-based patching + freeform fallback + frontmatter update + batch edit (supports `dryRun` diff preview)
👁️ view	`search` `global_search` `semantic_search` `outline` `read` `frontmatter_get` `bulk_read` `backlinks`	Fragment retrieval, cross-vault search, hybrid semantic search, read by heading, frontmatter read, bulk read, backlinks
🔄 workflow	`status` `transition` `history` `reset`	Petri net state machine control
⚙️ system	`status` `reindex` `overview` `overview_status` `prepare_overview` `save_overview`	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.

🚀 Quick Start

Prerequisites

Node.js >= 22
(Optional) Ollama for higher-quality embeddings

📦 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 -y auto-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

Mode	Use case	How it works
📡 `stdio` (default)	Single-client desktop apps (Claude Desktop)	Reads/writes stdin/stdout; 1:1 connection
🌊 `sse`	Multi-client setups (Docker, Claude Code)	HTTP server with SSE streams; one connection per client

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:

`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.

🏗️ 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-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):

Mechanism	When	What the agent sees
`instructions` field	MCP handshake	`vault_scope` + tool summary
MCP Resources	On-demand	`vault://overview` (stats + overview + conventions)
First-call priming	First tool call per session	`vault_scope` + hint to read `vault://overview`
Tool descriptions	Tool listing	`vault_scope` string for routing

Modes

Mode	How overview is managed
`assisted` (default)	Host agent calls `system.prepare_overview` → generates prose → calls `system.save_overview`
`manual`	You author `meta/overview.md` yourself; server creates stub but never overwrites

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/:

File	Purpose	Managed by
`meta/overview.md`	Vault description + `vault_scope` routing hint	Host agent (assisted) or you (manual)
`meta/contract.md`	Tool usage conventions (frontmatter schema, search hints, naming)	Created once, never overwritten

Tip: Keep vault_scope short and specific — it tells MCP hosts what information this vault can answer.

🚢 CI/CD & Release

Fully automated via GitHub Actions and Semantic Release:

Workflow	Trigger	What it does
PR Check	Pull request to `main`	Lint → Build → Test
Release	Push to `main`	Lint → Test → Semantic Release (NPM + GitHub Release) → Docker build & push to `ghcr.io`

Versioning follows Conventional Commits — feat: = minor, fix: = patch, feat!: / BREAKING CHANGE: = major
Docker images are built for linux/amd64 and linux/arm64 via 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 SafePath value 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

📄 License

MIT

Install Server

license - permissive license

quality

maintenance

How are these scores calculated?

Maintenance

–Maintainers

6dResponse time

1dRelease cycle

29Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Tools

Appeared in Searches

GitHub repository for litopys-dev/litopys project

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/wirux/mcp-markdown-vault'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

URL: https://glama.ai/mcp/servers/wirux/mcp-markdown-vault

⇱ mcp-markdown-vault by wirux | Glama