# obsidian-vault-mcp

An [MCP](https://modelcontextprotocol.io) server for an **Obsidian vault**, designed to
work as a [claude.ai / Claude Desktop custom connector](https://support.claude.com/en/articles/11175166)
— 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](https://github.com/crosbyh/obsidian-headless-sync-docker)
or Syncthing) — with bidirectional sync, notes written here appear on all your devices.

Built with [FastMCP](https://gofastmcp.com); 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`](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`](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

```bash
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

```bash
uv sync
uv run pytest
```

## License

MIT