obsidian-vault-mcp

An MCP server for an Obsidian vault, designed to work as a claude.ai / Claude Desktop custom connector — so Claude can search your notes, save conversation summaries, and append to your daily note from the web or desktop app.

No Obsidian plugins and no REST API: the vault is just a folder of markdown files, and this server operates on it directly. Run it next to a synced copy of your vault (e.g. via obsidian-headless-sync-docker or Syncthing) — with bidirectional sync, notes written here appear on all your devices.

Built with FastMCP; authentication uses GitHub OAuth via FastMCP's OAuth proxy, restricted to an allowlist of GitHub usernames.

Tools

Set READ_ONLY=true to register only the first three.

Safety model

• Writes are refused under protected paths (.obsidian/, .trash/, .git/ by default — add your template/config folders).

• Overwrites require an explicit overwrite=true, and the tool descriptions instruct the model to read a note before replacing it.

• Before any existing note is modified, its previous version is copied to OBS_BACKUP_DIR — outside the vault, so backups don't ride your vault sync.

• Path handling confines all access to the vault directory (no traversal).

Related MCP server: Obsidian MCP Server

Vault conventions are config, not code

Your vault probably has its own frontmatter templates, daily-note location, and folder taxonomy. Mount a YAML file (see vault-config.example.yml) to teach the server:

• the conversations folder and frontmatter template,

• the daily-note path scheme, seed template, and section heading,

• body-structure guidance injected into the save_conversation tool description,

• protected paths and search excludes,

• extra conventions text for the model (tag style, wikilink habits, ...).

Everything defaults to a sensible generic layout if no config is mounted.

Setup

1. GitHub OAuth app (connector authentication)

1. https://github.com/settings/developers → OAuth Apps → New OAuth App.

2. Authorization callback URL: https://your-server.example.com/auth/callback (your MCP_BASE_URL + /auth/callback).

3. Register, generate a client secret, and set GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET / ALLOWED_GITHUB_USERS.

Leaving the client ID/secret unset runs the server unauthenticated — local testing only.

2. Configuration reference

3. Run it

See compose.example.yml. Mount your synced vault at /vault, your conventions at /config/vault.yml, and persist /data (OAuth registrations + note backups). Expose it publicly at MCP_BASE_URL through your reverse proxy; optionally restrict ingress to Anthropic's egress range (160.79.104.0/21).

Consider starting with READ_ONLY=true, verifying search/read behave against your real vault, then enabling writes.

4. Verify, then connect Claude

npx @modelcontextprotocol/inspector   # → https://your-server.example.com/mcp

Then claude.ai (or Claude Desktop) → Settings → Connectors → Add custom connector with the same URL. You'll land on GitHub's authorize page; approve, and the tools appear. Try: "what have I been working on this week?" or "save this conversation to my vault".

Why CONSENT_MODE=external is the default

FastMCP's built-in consent page (as of 3.4.4) regenerates its CSRF token on every GET of the consent URL. Browsers and claude.ai routinely prefetch that URL, invalidating the token the visible page holds, so submitting the form fails with "Invalid or expired consent token". external skips that page and delegates consent to GitHub's own authorization screen. The client redirect-URI allowlist (claude.ai + localhost by default) prevents the classic risk of a consent-less flow — an arbitrary dynamically-registered client silently capturing an authorization code.

Failure modes

• GitHub login succeeds but tools are denied → your login isn't in ALLOWED_GITHUB_USERS (check logs for denied authenticated GitHub user).

• "note already exists" → deliberate; read the note, then append, merge, or retry with overwrite=true.

• Connector breaks after a redeploy → /data wasn't persisted, or the GitHub client secret changed (registration storage is keyed to it). Re-add the connector.

• Writes don't show up on your devices → check your sync container; this server only writes files, syncing them is the sync layer's job.

Development

uv sync
uv run pytest

License

MIT