obsidian-vault-mcp

MCP server + Obsidian Sync in one container. It keeps a live local copy of your Obsidian vault (via the official obsidian-headless sync client) and exposes it over MCP Streamable HTTP with bearer-token auth, so Claude can read and write your notes from any device: web, mobile, or desktop. Edits made by Claude sync back to all your devices through Obsidian Sync.

Claude (any device) --HTTPS--> obsidian-vault-mcp --/vault--> ob sync --continuous <--> Obsidian Sync <--> your devices

Requires an Obsidian Sync subscription. Not affiliated with Obsidian or Anthropic.

Quick start (Docker)

docker run -d --name obsidian-vault-mcp \
  -p 3000:3000 \
  -v /path/to/appdata/vault:/vault \
  -v /path/to/appdata/data:/data \
  -e OBSIDIAN_EMAIL=you@example.com \
  -e OBSIDIAN_PASSWORD='...' \
  -e OBSIDIAN_TOTP_SECRET='BASE32SECRET' \
  -e OBSIDIAN_VAULT='My Vault' \
  --restart unless-stopped \
  ghcr.io/jakergirard/obsidian-vault-mcp:latest

Watch the log on first start: it installs obsidian-headless, logs in, pulls the vault, prints the generated MCP access token, then serves MCP at http://<host>:3000/t/<token>/mcp.

Prefer not to put credentials in env vars? Leave OBSIDIAN_EMAIL/OBSIDIAN_PASSWORD unset and run the interactive login once instead; the session persists in /data:

docker exec -it obsidian-vault-mcp ob login

Unraid

A Community Applications template lives in unraid/obsidian-vault-mcp.xml. Until it is listed in CA, add this repo as a template repository: Docker > Template Repositories > add https://github.com/jakergirard/obsidian-vault-mcp, then add the container from the template.

Environment variables

Volumes: /vault (the synced vault) and /data (Obsidian Sync session, obsidian-headless install, generated token). Both should be persistent.

Exposing it to Claude

Important: Claude web and mobile connectors originate from Anthropic's cloud, not from your device. A LAN or Tailscale IP is not reachable from there. Pick one:

1. Tailscale Funnel (recommended if you run Tailscale): on the Docker host, tailscale funnel --bg 3000. You get https://<host>.<tailnet>.ts.net with TLS, and nothing else on your network is exposed. Requires HTTPS certs and the funnel node attribute enabled in your tailnet policy.
2. Cloudflare Tunnel: point a cloudflared tunnel at http://<host>:3000 on a hostname you own. On Unraid: run the cloudflared container from Community Applications with a remotely-managed tunnel token, then add a public hostname in Zero Trust with service http://<unraid-ip>:3000.
3. Reverse proxy: any HTTPS reverse proxy (Nginx Proxy Manager, Caddy, Traefik) forwarding to port 3000. No websockets needed; the server answers plain JSON. nginx-based proxies (including NPM) default to 1 MB request bodies, which fails large note writes with a 413; raise client_max_body_size to 16m to match the server limit.
4. LAN / tailnet only: no public exposure, but then only clients that connect from your own machines work, e.g. Claude Desktop or Claude Code pointed at http://<tailscale-ip>:3000/t/<token>/mcp. Claude web and mobile will not work in this mode.

Unraid + Tailscale Funnel walkthrough (recommended on Unraid)

The template pre-stages the entire Tailscale config with Tailscale disabled; enabling it is one toggle:

1. Edit the container > Use Tailscale > on
2. Hostname, Funnel mode, port 3000, and state dir come pre-filled from the template; adjust the hostname if you want a different URL
3. Apply, open the container log, click the To authenticate, visit... link to approve the node on your tailnet (approve Funnel if prompted)
4. One-time, tailnet-wide: admin console > DNS > enable HTTPS Certificates (first cert issuance can take a minute and may log a few retries)
5. Admin console > Machines > your container node > Disable key expiry, or the node silently drops off the tailnet after ~180 days

Connector URL: https://<hostname>.<tailnet>.ts.net/t/<token>/mcp

Connecting Claude

1. Claude Settings > Connectors > Add custom connector
2. URL: https://<your-public-hostname>/t/<your token>/mcp (token is in the container log or /data/mcp_token)
3. Leave the OAuth fields blank
4. Enable the connector in a chat and ask Claude to list your vault

The URL carries the token because Claude's custom connector dialog offers no header or token field, only OAuth. If that ever changes, header auth may return; for now the URL is the credential.

Tools

All paths are jailed to /vault.

Security notes

• The URL is the credential: anyone who has it can read and write your entire vault. Treat the full URL like a password. Rotate by changing MCP_TOKEN (or deleting /data/mcp_token) and restarting; the old URL dies instantly.
• URLs land in logs more readily than headers do, so don't paste the connector URL anywhere you wouldn't paste a password.
• Only expose the server over HTTPS (all three public recipes above provide it).
• READ_ONLY=true if you only want Claude reading notes.
• Vault contents may include sensitive material; think before exposing.

Why isn't obsidian-headless in the image?

The obsidian-headless npm package is published as UNLICENSED, which does not grant redistribution rights, so this image does not bundle it. The entrypoint installs it from npm on first start (into /data, so it persists across container updates). The CLI surface (ob login, ob sync-setup, ob sync --continuous) may change upstream; pin OBSIDIAN_HEADLESS_VERSION if a new release breaks something, and file an issue.

License

MIT