obsidian-vault-mcp
An MCP server for an Obsidian vault, designed towork as a claude.ai / Claude Desktop custom connector— so Claude can search your notes, save conversation summaries, and append to yourdaily note from the web or desktop app.
No Obsidian plugins and no REST API: the vault is just a folder of markdown files, andthis server operates on it directly. Run it next to a synced copy of your vault (e.g.via obsidian-headless-sync-dockeror Syncthing) — with bidirectional sync, notes written here appear on all your devices.
Built with FastMCP; authentication uses GitHub OAuth viaFastMCP'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/bydefault — add your template/config folders). - Overwrites require an explicit
overwrite=true, and the tool descriptions instructthe 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, andfolder 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_conversationtool 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)
- https://github.com/settings/developers → OAuth Apps → New OAuth App.
- Authorization callback URL:
https://your-server.example.com/auth/callback(yourMCP_BASE_URL+/auth/callback). - 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 — localtesting 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 yourreal 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 connectorwith the same URL. You'll land on GitHub's authorize page; approve, and the toolsappear. Try: "what have I been working on this week?" or "save this conversationto 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 GETof the consent URL. Browsers and claude.ai routinely prefetch that URL, invalidatingthe token the visible page holds, so submitting the form fails with "Invalid orexpired consent token". external skips that page and delegates consent to GitHub'sown authorization screen. The client redirect-URI allowlist (claude.ai + localhost bydefault) prevents the classic risk of a consent-less flow — an arbitrarydynamically-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 fordenied authenticated GitHub user). - "note already exists" → deliberate; read the note, then append, merge, orretry with
overwrite=true. - Connector breaks after a redeploy →
/datawasn't persisted, or the GitHubclient 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 serveronly writes files, syncing them is the sync layer's job.
Development
uv sync
uv run pytest
License
MIT
