vault-mcp-server

Give Claude Code persistent memory with a Markdown vault.

An MCP server that turns any folder of Markdown files into a searchable, structured knowledge base. Claude Code can list, read, write, edit, search, and summarize your vault — across sessions, across machines.

What it does

• 7 tools exposed via MCP: vault_list, vault_read, vault_write, vault_edit, vault_summary, vault_search, vault_reindex

• Semantic search powered by ChromaDB + sentence-transformers — ask questions in natural language, get relevant chunks back instead of full files

• Metadata parsing — extracts status, dates, and custom fields from **Key:** Value patterns in your Markdown

• Multilingual — search and metadata work in English and Spanish out of the box

• Incremental indexing — only re-embeds files that changed since last startup

Related MCP server: pando

Why Markdown

Markdown is the only format that is simultaneously human-readable, version-controllable, and LLM-friendly. No database to manage, no migration scripts. Your vault is just files — back them up with git, sync them with Nextcloud, edit them in Obsidian.

Architecture

┌─────────────────────┐     ┌──────────────────────┐
│  Claude Code         │────>│  vault-mcp-server     │
│  (any machine)       │<────│  (FastMCP + HTTP)     │
└─────────────────────┘     └──────┬───────────────┘
                                   │
                          ┌────────▼────────┐
                          │  Markdown Vault  │
                          │  (any folder)    │
                          └────────┬────────┘
                                   │
                          ┌────────▼────────┐
                          │  ChromaDB        │
                          │  (semantic index)│
                          └─────────────────┘

Quick start

1. Clone and configure

git clone https://github.com/thebackpackdevorg/vault-mcp-server.git
cd vault-mcp-server

Edit docker-compose.yml to point to your Markdown folder:

volumes:
  - /path/to/your/markdown-vault:/vault

2. Run

docker compose up -d

The server starts on port 8091 with Streamable HTTP transport.

3. Register in Claude Code

claude mcp add vault http://localhost:8091/mcp -t http

Or add to ~/.claude/settings.json:

{
  "mcpServers": {
    "vault": {
      "type": "http",
      "url": "http://localhost:8091/mcp"
    }
  }
}

4. Use it

You: "What do I have documented about Docker networking?"

Claude: *calls vault_search("Docker networking")* → returns relevant chunks

You: "Update the status in homeserver-backlog.md to Done"

Claude: *calls vault_edit("homeserver/homeserver-backlog.md", "**Status:** Active", "**Status:** Done")*

Remote deployment

To access the vault from other machines, expose it through a reverse proxy. The server supports an optional OAuth layer for authentication when deployed remotely.

With Cloudflare Tunnel + Access

1. Create a Cloudflare Tunnel pointing to localhost:8091

2. Add a Cloudflare Access policy with a Service Token

3. Configure Claude Code on remote machines:

{
  "mcpServers": {
    "vault": {
      "type": "http",
      "url": "https://vault.yourdomain.com/mcp",
      "headers": {
        "CF-Access-Client-Id": "${VAULT_CF_CLIENT_ID}",
        "CF-Access-Client-Secret": "${VAULT_CF_CLIENT_SECRET}"
      }
    }
  }
}

With built-in OAuth

Set OAUTH_ISSUER_URL and optionally OAUTH_PIN in your environment to enable the built-in OAuth 2.1 provider with a PIN-based approval page.

Combining OAuth with Cloudflare Access

When OAuth is enabled, requests that come through a Cloudflare Access application can skip the OAuth flow. The server verifies the Cf-Access-Jwt-Assertion JWT (RS256 signature against your team's public keys, issuer and audience) before trusting it. Set both CF_ACCESS_TEAM_DOMAIN and CF_ACCESS_AUD to enable this; if either is missing, the header is ignored and every request must complete OAuth.

The SSE vs Streamable HTTP gotcha

If you're deploying behind Cloudflare (or any proxy that buffers SSE), you may hit a silent failure where Claude Code connects but never gets responses.

The fix: This server uses Streamable HTTP (not SSE). Make sure your proxy passes through the Accept: application/json, text/event-stream header correctly. The server includes a middleware that injects this header if missing.

Tools reference

Configuration

config.yaml

vault:
  path: "/vault"

server:
  host: "0.0.0.0"
  port: 8080

search:
  chroma_path: "/app/chroma_data"
  model: "paraphrase-multilingual-MiniLM-L12-v2"

Environment variables (override config.yaml)

Metadata conventions

The server parses **Key:** Value patterns in the first 15 lines of each file:

# My Project

**Status:** Active
**Created:** 2026-01-15
**Last Updated:** 2026-03-01

Recognized status values: Active, Pending, Paused, Done (and Spanish equivalents).

Stack

• Python 3.12 + FastMCP

• ChromaDB for vector storage

• sentence-transformers (paraphrase-multilingual-MiniLM-L12-v2) for embeddings

• Docker + uv for fast builds

License

MIT