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

Tool	Description
read_note	Raw markdown of a note (vault-relative path, .md optional)
search_vault	Case-insensitive text search, optionally scoped to a folder
list_recent_notes	Notes modified in the last N days
save_conversation	Dated conversation-summary note with your frontmatter template
append_daily	Append a section to today's daily note (seeds it if missing)
write_note	Create a note verbatim; refuses to overwrite unless told to
append_to_note	Append to any note, creating it if needed

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

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

Variable	Required	Description
OBS_VAULT	no	Vault directory (default /vault)
OBS_CONFIG	no	Conventions YAML (default /config/vault.yml; optional)
OBS_BACKUP_DIR	no	Pre-modification backups (default /data/vault-backups; "" disables)
OBS_SEARCH_MAX	no	Max search results (default 50)
READ_ONLY	no	true = read/search tools only
TZ	no	Timezone used for daily-note and conversation dates
MCP_BASE_URL	with auth	Public URL of this server
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET	with auth	OAuth app credentials (or _FILE)
ALLOWED_GITHUB_USERS	with auth	Comma-separated GitHub logins allowed in
CONSENT_MODE	no	external (default), true, remember, false — see below
ALLOWED_CLIENT_REDIRECT_URIS	no	Redirect-URI patterns clients may register (default: claude.ai callback + localhost)
HOST / PORT / MCP_PATH	no	Bind address (0.0.0.0), port (8000), path (/mcp)
FASTMCP_HOME	no	OAuth client-registration storage (/data in Docker)

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