vault-mcp

A small remote MCP server that lets an LLM (claude.ai, Claude Code, mobile) search, read, and write an Obsidian vault organised with the PARA method — and save URLs as notes.

The server holds no LLM of its own. It is a deterministic set of tools; the connecting model is the brain. When you ask it to "save this to my vault", the model calls vault_taxonomy to see your folder structure, picks the right folder itself, and calls vault_write.

Claude Desktop / claude.ai / Claude Code
        │  HTTPS + GitHub OAuth (or Bearer token)
        ▼
 reverse proxy / TLS  ──►  vault-mcp (this server)  ──►  ~/Obsidian/YourVault

Docs: Architecture · Authentication · Deployment · Changelog

Tools

Related MCP server: Neuro Vault MCP

Safety

• Every path is resolved and confined to the vault root — no .. traversal, no absolute paths, no symlink escapes.

• Writes are allowed only under 01-Inbox/, 10-Projects/, 20-Areas/, 30-Resources/, docs/.

• Reads of regenerable index/map/log artifacts and legacy wiki backups are refused (they are huge and waste tokens).

• Auth is required: a static Bearer token or GitHub OAuth with a user allowlist (see Authentication).

Install

git clone https://github.com/KORThomasJeong/vault-mcp.git
cd vault-mcp
cp .env.example .env        # then edit .env
uv sync

Generate an auth token:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Configure

All config is via environment (see .env.example):

The search and URL-save tools shell out to optional companion CLIs. If you don't have them, those tools simply report that they're disabled — read/write/taxonomy still work.

Run

uv run vault-mcp
# serves Streamable HTTP at http://127.0.0.1:8848/mcp

Expose it through your existing reverse proxy (nginx / Nginx Proxy Manager / Caddy / Cloudflare) so that https://your-host/mcp forwards to 127.0.0.1:8848. Enable WebSocket/streaming pass-through and disable response buffering so SSE works (for nginx: proxy_buffering off;, a long proxy_read_timeout).

Authentication

OAuth authenticates, the allowlist authorizes. In github mode the server refuses to start unless GITHUB_ALLOWED_USERS is set — otherwise any GitHub account could connect, which is more open than a token.

Both at once: set MCP_AUTH_TOKEN alongside github mode and the server accepts GitHub OAuth and the static token simultaneously (MultiAuth). Details in docs/AUTHENTICATION.md.

Set up GitHub OAuth (github mode)

1. Register an OAuth App at https://github.com/settings/developers → New OAuth App:

   • Homepage URL: https://your-host

   • Authorization callback URL: https://your-host/auth/callback

2. Copy the Client ID, generate a Client secret, and put them plus BASE_URL=https://your-host, AUTH_MODE=github, and GITHUB_ALLOWED_USERS=<your-login> in .env.

3. Restart the server.

Connect from Claude Code

# token mode
claude mcp add --transport http vault https://your-host/mcp \
  --header "Authorization: Bearer <your-token>"

# github mode (OAuth — opens a browser)
claude mcp add --transport http vault https://your-host/mcp

Connect from Claude Desktop / claude.ai

Settings → Connectors → add a custom connector pointing at https://your-host/mcp. Use github mode — the desktop/web connector UI authenticates via OAuth and has no field for a static Bearer token.

Develop

uv run --extra dev pytest

License

MIT