📁 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

💡 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
🗺️	Vault overview	Structural map of the vault — total file count, recursive folder tree with file counts and last modification dates per folder
📦	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` `line_replace` `string_replace` `frontmatter_set` `batch`	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`	Server health, indexing info, vault structure overview

All tool responses include contextual hints based on the current workflow state.

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

🐳 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-obsidian.git
cd mcp-obsidian
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
`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

🏗️ 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.

🚢 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

318 tests across 31 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

mcp-markdown-vault