Obsidian Vault MCP

A self-hosted Model Context Protocol server for private Obsidian vaults stored in GitHub. It runs on Cloudflare Workers, authenticates the vault owner with OAuth 2.1, and exposes Markdown notes, an Obsidian-compatible link graph, and a durable event stream for vault automations.

The same Worker also serves an optional private web portal with a vault switcher, Markdown reader, content search, an interactive Graph Explorer, an ephemeral read-only AI chat with verified note citations, and callback-driven vault snapshots to Google Drive.

The server does not run Obsidian. It derives links, backlinks, aliases, tags, embeds, unresolved references, and shortest paths from an immutable GitHub tree snapshot.

Security model

The default deployment is deliberately single-owner:

• One immutable GitHub user ID may authorize MCP clients.

• Only repositories in GITHUB_REPOSITORIES are addressable.

• A fine-grained GitHub token must be restricted to exactly those repositories.

• Each MCP client requires an explicit consent screen after GitHub login.

• Read-only deployments do not register the write tool.

• Writable deployments require vault:write; updates use the current Git blob SHA and reject stale or blind overwrites.

• Secrets stay in Cloudflare and are never part of this repository.

Do not add unrelated users to a deployment backed by one shared token. See Multi-user architecture for the correct isolation model.

Related MCP server: Obsidian MCP (pgvector + Ollama, self-hosted)

Tools

Deploy your own instance

Follow the complete self-hosting guide. The short version is:

1. Fork this repository.

2. Create Cloudflare KV, D1, and Queues resources plus an OAuth App on GitHub.

3. Create a fine-grained GitHub token restricted to selected vault repositories.

4. Copy wrangler.example.jsonc to the ignored wrangler.jsonc and enter only non-secret deployment values.

5. Upload the four base runtime secrets to Cloudflare, apply the D1 migrations, and deploy. Add OPENAI_API_KEY only when enabling an AI automation.

6. Connect an MCP client to https://your-host/mcp and approve its consent screen.

7. After the manual deployment passes its smoke tests, connect Cloudflare Workers Builds to the fork or enable the protected GitHub Actions alternative.

Web portal

The root URL serves the portal. It reuses the GitHub OAuth callback but has its own host-only browser session; MCP bearer grants are never exposed to frontend JavaScript. The browser receives neither GitHub credentials nor the OpenAI API key.

Configure chat with a Worker secret and optional non-secret settings:

bunx wrangler secret put OPENAI_API_KEY

• Chat enables automatically when OPENAI_API_KEY exists. Set WEB_CHAT_ENABLED=false to turn it off explicitly, or true to make a missing secret fail the health check.

• OPENAI_CHAT_MODEL selects the default among gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna; users can choose the model and reasoning level per conversation.

• WEB_CHAT_DAILY_LIMIT defaults to 50 requests per GitHub user per UTC day.

• Chat history stays in browser memory. Prompt, note text, and answers are not stored in D1.

• A read-only agent can search, read exact note revisions, and inspect the graph within one selected vault or note. The UI shows its tool activity and aggregate token usage; every citation is checked against retrieved evidence.

See Web portal and vault chat for the API, privacy model, and current multi-user boundary.

The portal's Graph Explorer filters notes by path or tag, shows incoming and outgoing link counts, and finds bounded shortest connection trails without exposing note bodies to the browser graph response.

Vault sync callbacks

The portal can connect a selected vault to Google Drive. GitHub remains canonical: every detected revision queues a coalesced internal callback that uploads a complete repository ZIP (notes, attachments, and .obsidian settings) into an app-created Drive folder. The integration requests only the non-sensitive drive.file scope, so it cannot browse unrelated Drive content.

Set GOOGLE_CLIENT_ID as a Worker variable and upload GOOGLE_CLIENT_SECRET plus a random 32-byte SYNC_CREDENTIALS_KEY as Worker secrets. Register https://your-host/api/sync/google/callback as the exact Google OAuth redirect URI. See Vault sync destinations for setup, encryption, retries, and the iCloud boundary.

Development

bun install --frozen-lockfile
bun run check

bun run check runs strict TypeScript, 80+ unit tests, a production dependency audit, and a Wrangler bundle dry-run. CI runs the same command without deployment credentials.

For local Worker development, bun run dev builds the portal and applies local D1 migrations before starting Wrangler. bun run web:dev provides frontend HMR and proxies API/auth routes to Wrangler on port 8787; use a separate development GitHub OAuth App whose callback points at your local origin, or test the authenticated flow on a preview deployment.

Limits

• Up to 1,000 Markdown notes and 8 MB of Markdown source per graph snapshot.

• Up to 512 KB per note.

• Graph data is cached by repository and immutable Git tree revision for five minutes.

• Hidden paths and non-Markdown files are never exposed as notes.

• Writes create Git commits; rename and delete operations are intentionally unavailable.

• GitHub is canonical: pushes made by Obsidian, the MCP, GitHub's UI, or another Git client produce the same events.

• Automation handlers are internal and explicitly configured; summarize-note writes only managed summaries, while authenticated sync destinations reuse the durable callback queue. Arbitrary outbound callback URLs are not supported.

• One repository receives immediate webhook delivery per deployment; every allowlisted vault is still reconciled on the fifteen-minute schedule.

See Vault events and automations for delivery, filtering, retries, and the write-loop policy.

Project status

The personal self-hosted model is implemented. Shared multi-user hosting is a separate design and requires a GitHub App installation per tenant; it is not enabled by this codebase today.

See Security, security model, and contributing.

License

MIT