obsidian-mcp

A self-hosted MCP server + management UI for your Obsidian vault. One container gives you:

• An MCP server (Streamable HTTP) with 10 carefully designed tools for reading, searching, editing, and organizing notes — built for Claude Desktop, claude.ai, and Claude Code.

• A passkey-protected management UI (passkeys only, no passwords) for tokens, OAuth connections, sync, and snapshot history.

• OAuth 2.1 + Dynamic Client Registration so Claude Desktop/claude.ai connect with just a URL, plus named bearer tokens for Claude Code and other clients.

• Optional Obsidian Sync via the official obsidian-headless client (ob sync --continuous), supervised by the server and configured entirely from the web UI — including end-to-end-encrypted vaults. Requires an Obsidian Sync subscription; skip it and bring your own sync (Syncthing, git, nothing).

• Automatic git snapshots of the vault (debounced after every MCP mutation, before destructive operations, hourly, and at shutdown) stored in a bare repo outside the vault. Browse and restore from the UI.

All state lives in a single bind-mounted ./data directory:

data/
├── Vault/               your Obsidian vault
├── db/app.db            server state (passkeys, tokens, OAuth grants)
├── obsidian-headless/   ob CLI auth + sync state
└── snapshots/vault.git  bare git repo with vault history

Quick start

The server must be reachable over HTTPS (passkeys and Claude connectors require it). The recommended setup is a tunnel — no ports exposed at home:

• deploy/docker-compose.gatecrash.yml — self-hosted Gatecrash tunnel

• deploy/docker-compose.cloudflared.yml — Cloudflare Tunnel

mkdir obsidian-mcp && cd obsidian-mcp
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/jclement/obsidian-mcp/main/deploy/docker-compose.gatecrash.yml
# create .env with tunnel credentials (see comments in the compose file)
docker compose up -d
docker compose logs app        # ← copy the FIRST-RUN SETUP token

Just want to try it locally (no tunnel, no published image)? From a checkout:

docker compose -f deploy/docker-compose.local.yml up --build
docker compose -f deploy/docker-compose.local.yml logs app   # ← setup token
# open http://localhost:3000/setup

Open https://your-host/setup, paste the token, and register a passkey. That passkey is now the only way into the management UI; add more from the Passkeys page.

Connect Claude Desktop / claude.ai

Settings → Connectors → Add custom connector → https://your-host/mcp. Claude discovers the OAuth endpoints, registers itself, and sends you to your server to approve with your passkey. Done.

Connect Claude Code

Create a token in the UI (Tokens → name it → copy once), then:

claude mcp add --transport http obsidian https://your-host/mcp \
  --header "Authorization: Bearer obmcp_..."

Connect Obsidian Sync (optional)

UI → Sync → sign in with your Obsidian account (+2FA), pick a remote vault, optionally provide the end-to-end encryption password. The server runs ob sync --continuous, restarts it with backoff if it dies, and shows a live log. Credentials are passed straight to the ob CLI and never stored by this server.

Related MCP server: obsidian-mcp

The MCP tools

Design notes:

• Safe concurrent editing. The vault can change underneath the server (Obsidian Sync). Every read returns a content hash; edits verify it and fail with a retryable error if the note changed. Whole-content replacement requires the hash. Writes are atomic (temp file + rename) and serialized per note.

• Obsidian-native behavior. Wikilink resolution, daily-note paths, templates, and link rewriting all honor the vault's .obsidian/ settings. The server never writes into .obsidian/.

• Recoverable by design. Deletes are soft (.trash/), every mutation is git-snapshotted, and destructive ops take a synchronous pre-snapshot.

Configuration

Security model

• Management UI: passkeys only, user verification required, discoverable credentials (one-tap). Sessions are DB-backed, HttpOnly, SameSite=Lax cookies.

• First-run trust: /setup requires a token printed to server logs (proof of box ownership); the page 404s once a passkey exists.

• Hostname handling: when PUBLIC_URL is unset the origin/rpID are derived from the proxy's forwarded headers, and the WebAuthn rpID is pinned at first-passkey setup — a later request arriving with a different host is rejected (use AUTH_RESET=1 to re-key if the hostname legitimately changes). WebAuthn's crypto binds each credential to the browser-signed origin regardless, so a forged forwarded header cannot impersonate your host.

• MCP: OAuth 2.1 (PKCE S256 mandatory, RFC 8414/9728 metadata, RFC 7591 DCR, refresh rotation with reuse detection) or static bearer tokens. All tokens stored as SHA-256 hashes, shown once, revocable from the UI; revocation also kills live streams.

• Host-header guard (DNS rebinding), Origin checks on /mcp, CSRF protection on the UI, rate-limited auth endpoints.

• data/db/app.db contains only hashes and public keys — safe to back up.

Development

Requires mise (pins bun + node) and git.

mise install
bun install
mise run dev          # server with hot reload + tailwind watch → http://localhost:3000
mise run test         # bun test (133 tests)
mise run typecheck
mise run docker:build
mise run ob:install   # optional: real obsidian-headless for local sync testing

Local dev uses the same ./data layout as production and passkeys work on http://localhost.

Recovery cheatsheet

# full vault history
git --git-dir data/snapshots/vault.git --work-tree data/Vault log --oneline

# restore everything to a snapshot
git --git-dir data/snapshots/vault.git --work-tree data/Vault checkout <sha> -- .

# lost your passkey?
AUTH_RESET=1 docker compose up -d   # re-enters setup mode; unset afterwards

License

MIT © Jeff Clement