secondbrain-mcp

One server. One connector. Every Claude client.

There is no chat UI to build. A custom connector is configured once, on your account, at claude.ai → Customize → Connectors → "+" → Add custom connector. From then on it is available in Claude Desktop, claude.ai, Cowork and the iOS and Android apps. Same server, same vault, same tools everywhere.

Claude connects to this remote MCP server from Anthropic's cloud, so the server must be on the public internet with real TLS. Deploy target: https://brain.lous.info on the shared Hetzner host. Platform services are owned by hetzner-infra; this repo deploys only the app plus nginx / observability drop-ins (same pattern as Padel Vibe / Unseen Servant).

Routes

route	who calls it	auth
/mcp	Claude, every client	GitHub OAuth (allow-listed login)
/authorize, /token, /auth/*, /.well-known/*	Claude OAuth handshake	public endpoints of the OAuth proxy
/	optional browser view	optional nginx basic auth
/refresh	GitHub webhook (optional)	X-Webhook-Secret
/health	Docker / CI healthcheck	none

Auth

Env	Role
GITHUB_OAUTH_CLIENT_ID / GITHUB_OAUTH_CLIENT_SECRET	GitHub OAuth App for the Claude connector
GITHUB_ALLOWED_USERS	Comma-separated GitHub logins (e.g. TomLous) — everyone else is rejected
VAULT_GITHUB_PAT	Fine-scoped PAT for HTTPS clone/pull/push of the vault (separate from OAuth)

In Claude: add connector URL https://brain.lous.info/mcp, leave OAuth Client ID/Secret empty (Dynamic Client Registration), then Connect and sign in with GitHub as an allow-listed user.

How it works

 phone browser ─┐                    ┌─ shared nginx :443 ─┐
                ├── https ───────────┤                     ├── secondbrain-mcp:8000
 Claude cloud ──┘                    └─────────────────────┘         │
                                                                     ├─ /vault  (git clone)
                                                                     │     ▲
                                                                     │     │ pull every 5 min
                                                           github.com/.../SecondBrain
                                                                     ▲
                                                        Obsidian Git │ auto-commit
                                                                  laptop

The container never touches your laptop. GitHub is the sync bus.

Deploy (Hetzner)

See docs/hetzner-deploy.md.

# one-time on the server
sudo mkdir -p /opt/secondbrain/deploy/nginx
sudo chown -R deploy:deploy /opt/secondbrain
cp .env.example /opt/secondbrain/deploy/.env   # fill secrets
chmod 600 /opt/secondbrain/deploy/.env

Push to main builds ghcr.io/<owner>/secondbrain-mcp, SSHs to Hetzner, installs the nginx vhost into /opt/hetzner/deploy/nginx/conf.d/, syncs observability drop-ins, and health-checks https://brain.lous.info/health.

GitHub Environment Hetzner: secret HETZNER_SSH_KEY, vars HETZNER_HOST, HETZNER_USER (same as the other apps).

Local

cp .env.example .env                  # set VAULT_GITHUB_PAT + GitHub OAuth vars
docker compose -f docker-compose.dev.yml up -d --build
curl -s localhost:8770/health

Tools

Reads: search_vault, get_note, neighbors Lenses: next_actions, renewals, annual_cost, open_unknowns, stale_facts, check_graph Writes: capture, answer_unknown

Every write is pull --rebase → edit → check_graph.py → commit → push, and rolls back if the validator reports dangling links.

Known limits

• answer_unknown does string surgery on frontmatter; fine for current vault shapes, not exotic YAML.
• renewals needs notes with renewal_date populated.