Back to search
vault-mcp
MCP serverGitHub
Personal knowledge vault as a remote MCP server with built-in single-user OAuth 2.1, hybrid retrieval and a retrieval eval
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/igmizo--vault-mcp)HTML
<a href="/listings/igmizo--vault-mcp"><img src="/api/listings/igmizo--vault-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 213 lines
- # vault-mcp
- Personal knowledge vault, served to Claude.
- A plain-markdown, git-versioned vault exposed as a **remote MCP server** with
- its own **single-user OAuth 2.1 authorization server**, published through a
- Cloudflare Tunnel and usable as a Claude custom connector from any device.
- An earlier build of this code has been running in production since
- mid-2026, guarding its owner's private notes.
- What is interesting in here:
- - **Remote MCP, stateless.** Streamable HTTP, a fresh server per request, no
- session state anywhere. Six tools.
- - **OAuth 2.1 written from the spec, for exactly one user.** Discovery
- metadata, Dynamic Client Registration, PKCE S256 only, rotating refresh
- tokens with reuse detection, tokens stored as hashes. About 800 lines,
- no auth library — [`server/src/oauth.ts`](server/src/oauth.ts).
- - **Hybrid retrieval.** A ripgrep keyword leg and a local-embedding semantic
- leg (EmbeddingGemma, no API, no key), fused with reciprocal rank fusion.
- The index heals itself on every query.
- - **A retrieval eval.** A labelled question set over a public fixture
- corpus; hit@k, MRR, nDCG, per-category breakdown, baseline diffs and a CI
- gate — [`docs/eval.md`](docs/eval.md).
- - **Backups you can restore.** Nightly encrypted git bundle plus restic,
- with a written restore drill — [`ops/README.md`](ops/README.md).
- - **One test that covers the lot.** `npm run smoke` boots the server against
- a throwaway vault and runs 107 end-to-end checks in seconds.
- ## Run it
- ```bash
- cd server
- npm install
- npm run build
- npm run smoke # full OAuth + MCP + git flow against a temp vault
- npm run eval:ci # metric self-test + eval on the fixture corpus
- ```
- Needs Node 20+ and `git`. To run the server itself, see [Deploy](#deploy).
- ## Architecture
- ```
- Claude (phone/web, via Anthropic cloud) Telegram bot (optional)
- │ https │ long-poll (outbound)
- ▼ ▼
- Cloudflare edge assistant listener (systemd,
- │ tunnel (outbound-only) chat + capture, sandboxed)
- ┌─ server ──────────────────────────────────────────────┼───────────────┐
- │ cloudflared ──► vault-mcp (MCP :3000, OAuth 2.1) ◄───┘ │
- │ │ isolated docker network, loopback publish │
- │ vault/ (markdown, git) ⇄ vault.git (bare, hooks) │
- │ │ ▲ │
- │ nightly: encrypted bundle + restic ──► offsite storage │
- └─────────────────────┼──────────────────────────┼──────────────────────┘
- │ Tailscale Serve │ git over Tailscale SSH
- ▼ ▼
- Claude Code (laptop) Obsidian on ~/vault (laptop)
- ```
- Every piece, schedule and runbook is in
- [`docs/how-it-works.md`](docs/how-it-works.md). The decisions behind it are in
- [`docs/decisions/`](docs/decisions/).
- ## What Claude gets
- | Tool | Does |
- | ----------------------- | ------------------------------------------------------------ |
- | `vault_search_notes` | regex/text search across the vault (ripgrep) |
- | `vault_semantic_search` | meaning-based search — concepts, paraphrase, cross-language; hybrid RRF with the keyword leg |
- | `vault_read_note` | read one note |
- | `vault_write_note` | create/append/overwrite a note + git auto-commit |
- | `vault_list_notes` | browse folders and notes |
- | `vault_recent_notes` | most recently modified notes |
- Every write is committed to git as author `vault-mcp`, so `git log` is an
- audit trail and `git diff` is your curation gate.
- ## Deploy
- Prereqs: a server with Docker, a domain on Cloudflare. About 15 minutes.
- 1. **Copy this folder to the server** (e.g. `/opt/vault-mcp`) and make the
- vault its own repo:
- ```bash
- cd /opt/vault-mcp
- cp -r vault-template vault
- cd vault && git init && git add . && git commit -m "vault: founding"
- ```
- 2. **Create the tunnel.** Cloudflare dashboard → Zero Trust → Networks →
- Tunnels → Create tunnel (Cloudflared). Copy the token. Add a public
- hostname: `vault.example.com` → service `http://vault-mcp:3000`.
- 3. **Configure environment:**
- ```bash
- cp .env.example .env
- # set VAULT_MCP_PUBLIC_URL=https://vault.example.com
- # set VAULT_MCP_PASSWORD to something strong: openssl rand -base64 24
- # paste CLOUDFLARE_TUNNEL_TOKEN
- ```
- 4. **Launch:**
- ```bash
- docker compose up -d --build
- curl -s https://vault.example.com/healthz # → {"ok":true,...}
- ```
- 5. **Connect Claude.** Settings → Connectors → Add custom connector → URL
- `https://vault.example.com/mcp` → Add → Connect. You land on the
- passphrase page; enter `VAULT_MCP_PASSWORD` once. Claude handles tokens
- and refresh from there.
- 6. **Laptop workflow (optional):** keep a bare repo next to the working
- tree, clone it over Tailscale SSH, open the folder in Obsidian, commit
- and push. Sync is event-driven — a `post-receive` hook updates the served
- tree on push, a `post-commit` hook propagates server-side writes back,
- and an hourly cron reconcile is the healing net.
- Semantic search needs the EmbeddingGemma model files pre-seeded on the data
- volume (runtime downloads are disabled on purpose) — see `ops/README.md`. A
- hosted OpenAI `text-embedding-3-large` backend ships dark as the escape
- hatch (`VAULT_MCP_EMBEDDER=openai` + key); switching either way is an env
- flip, the index rebuilds itself.
- ## Security model
- - **No inbound ports.** cloudflared makes outbound connections only; the MCP
- port is never exposed on the host. The compose network is isolated — keep
- it away from any other stack on the box.
- - **OAuth 2.1, single user.** PKCE S256 mandatory, Dynamic Client
- Registration, `client_id` bound to every code and refresh token. Claude
- connectors do not support static bearer tokens, which is why this server
- carries its own tiny authorization server.
- - **Rotating refresh tokens with reuse detection.** Every refresh
- invalidates the old pair. A rotated token that comes back later revokes
- every token descended from that login.
- - **Hashed tokens at rest.** Only SHA-256 hashes are stored; a leaked data
- volume leaks no live credentials. The state file is written atomically,
- mode 0600.
- - **Login throttling that cannot be dodged with a header.** Failed
- passphrase attempts are limited per client IP and globally. The client IP
- comes from a fixed trusted-proxy hop count, not from whatever
- `X-Forwarded-For` the caller sends. The trade-off: 30 wrong guesses lock
- new logins for 15 minutes; existing tokens keep working.
- - **Bounded open registration.** DCR has to be open for Claude, so it is
- capped: https or loopback redirects only, size and rate limits, an
- optional host allow-list. The consent page shows where the code will be
- sent, because the client name is whatever the registrant typed.
- - **Path safety.** Every path is resolved and confined to the vault; the
- smoke test asserts traversal is rejected.
- - **No secrets in the vault.** The server serves whatever is in the vault,
- so never write credentials into notes.
- Rotate access by changing `VAULT_MCP_PASSWORD` and deleting the
- `vault-mcp-data` volume (`docker compose down -v` keeps the vault, drops
- issued tokens), then reconnecting in Claude.
- ## Eval
- `server/scripts/eval.mjs` runs a labelled question set through the keyword,
- semantic and hybrid legs and reports hit@1/3/5, MRR@10, nDCG@10, recall@10,
- latency, and how well the top score separates answerable from unanswerable
- questions. The repo ships a synthetic 48-note fixture vault with 71
- questions in seven categories (keyword, paraphrase, cross-language,
- deep-section, distractor, exact-term, no-answer), so anyone can run it.
- The eval set used against the real vault is private, because the questions
- describe the notes. Point the runner at your own with
- `--vault <dir> --questions <file>`.
- Results on the fixture corpus with the production model (EmbeddingGemma):
- | Mode | hit@1 before → after | hit@5 before → after | nDCG@10 before → after |
- | -------- | -------------------- | -------------------- | ---------------------- |
- | keyword | 0.60 → 0.67 | 0.76 → 0.79 | 0.69 → 0.73 |
- | semantic | 0.83 (unchanged) | 1.00 (unchanged) | 0.92 (unchanged) |
- | hybrid | 0.68 → 0.89 | 0.87 → 1.00 | 0.80 → 0.94 |
- The first real-model run showed hybrid, the default, scoring below semantic
- alone: rank fusion let a weak keyword match outrank a note only the
- embeddings had found. The keyword leg now matches whole words, keeps
- identifiers such as `v1.4.2` or `--read-data-subset` whole, and scores with
- BM25; its rank only counts when a note contains the query's terms. Hybrid
- is now ahead of semantic, and the lead comes from exact identifiers: error
- codes, ports, config keys. The response also carries a confidence value
- that drops to zero when the query names an identifier no note contains.
- Both reports are committed, so the change is diffable. The lead over
- semantic is a handful of questions on a small synthetic corpus, and
- [`docs/eval.md`](docs/eval.md) says exactly how far to trust it and what
- is still weak.
- ## Layout
- - `server/` — the MCP server (TypeScript, strict). `src/oauth.ts` is the
- authorization server, `src/tools.ts` the six tools, `src/vault.ts` the
- filesystem + git layer, `src/semantic/` the embedder, chunker, index store
- and hybrid search.
- - `server/scripts/smoke.mjs` — the end-to-end test suite.
- - `server/eval/` — fixture vault, questions, baseline report.
- - `ops/` — backup, reindex, liveness and alert scripts, with runbooks.
- - `jobs/` — optional host jobs: a morning briefing and a Telegram listener.
- - `vault-template/` — starter vault and its conventions.
- - `docs/` — how it works, decision records, the eval, capture conventions.
- ## License
- MIT — see [`LICENSE`](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.