brain-mcp

Your second brain as a private git repo, wired into claude.ai.

A remote MCP server + web cockpit for a personal "second brain" made of plain markdown files in a private GitHub repo. Every new Claude chat can read your context (who you are, what you're working on, what you decided) and write back to it — through guarded, intent-shaped tools. A single-page web app renders the same brain as a live knowledge graph.

Runs entirely on the Cloudflare Workers free plan. No database, no vector store, no server to babysit: GitHub is the storage, git history is the backup, markdown is the format you'll still be able to read in 30 years.

What you get

• MCP connector for claude.ai — Streamable HTTP at /mcp, OAuth 2.1 + PKCE handshake handled by @cloudflare/workers-oauth-provider, GitHub login restricted to a single allowed account (yours).

• Read tools (tiered, token-efficient): list_brain (file map + one-line summaries), get_brain_file, search_brain, get_graph, brain_health.

• Write tools (intent-shaped — no raw "write anywhere"):

  • add_to_inbox(filename, content) — stage into inbox/, never overwrites.

  • append_decision(text) — append a dated entry to decisions/YYYY-MM.md (append-only).

  • update_now(content) — replace now.md, bump the updated: date.

  • upsert_project(name, content) — create/update projects/<slug>.md.

  • upsert_file(path, content) — general fallback, restricted to known folders.

  • delete_inbox_item(filename) — the only delete, restricted to inbox/.

• Guards on every write: refuses content that looks like an API key, token or private key; refuses paths outside the brain's folders; decisions/ is append-only; deletes are restricted to inbox/.

• Web cockpit at the Worker root (GitHub-gated session): force-directed knowledge graph (canvas + d3-force), file reader with wiki-links and backlinks, inline editor, inbox triage, health report (broken links, stale files, orphans), decision log, and a temporal replay of the brain's growth from git history. The UI language is currently French.

• Two themes, one anatomy ("Atelier") — stacked surfaces rather than rules: the room, the panel, the card, the control, each lifted by a soft shadow and an achromatic glaze instead of a heavier border. Generous radii, Inter for the human voice and JetBrains Mono for the machine voice (both self-hosted), and a neutral palette where color is semantic and rare: blue for selection, green for healthy, amber for attention, red for urgency. Dark mode is the default; light flips the same anatomy onto pale paper. A segmented switch (light | auto | dark) lives on the graph page and in the sidebar footer; auto follows the actual sunset/sunrise for your location (NOAA formula, no API). All deltas live in CSS tokens and GRAPH_SKINS — see design/guidelines.md. Set your coordinates in app/src/theme.ts and in the inline script of app/index.html (default: Paris).

• PWA share target — share a link/text from your phone straight into inbox/.

• Phone capture at /capture — a standalone box for the idea you'd otherwise lose in a notes app. Installable as its own home-screen icon (separate manifest, start_url: /capture), it renders before the graph loads and works offline: the text is queued in localStorage before the network is touched, so a dead tunnel or an expired session costs nothing — the queue drains on the next load and on online. Captures land appended to inbox/idees-YYYY-MM-DD.md, one dated line each, no folder and no classification: sorting is a separate, deliberate session. Optional pre-tag (to-do / réflexion / projet / question) while the context is still in mind.

Related MCP server: me-db

Architecture

claude.ai ──(OAuth 2.1 + PKCE)──► Worker (its own OAuth server)
                                    │  GitHub login = identity gate (ALLOWED_LOGIN)
                                    ▼
                              /mcp  Durable Object (MCP tools)
Browser ──(cookie session)──► /api + static SPA (Vite + React)
                                    │
                                    ▼
                     GitHub contents API — your private brain repo
                     (fine-grained PAT, server-side only)

Two credentials, two jobs, never mixed:

• The GitHub OAuth App only proves who you are. Its token is never used to touch the repo.

• A fine-grained PAT (GITHUB_BRAIN_TOKEN, scoped to the brain repo only, Contents read/write) does all repo access, server-side. claude.ai never sees it.

The brain repo

Create a separate, private repo (e.g. your-brain-repo) holding plain markdown. The layout the tools expect:

README.md            # how your brain works (also read by Claude)
identity.md          # who you are — stable base context
preferences.md       # how you like to work
now.md               # current focus + deadlines (updated often)
context/             # long-lived context (company, school, protocols…)
people/              # one file per person
projects/            # one file per project
domains/             # knowledge areas
decisions/YYYY-MM.md # append-only decision log
personal/            # whatever is yours
inbox/               # raw captures, triaged later

Files carry a small YAML frontmatter the graph and health report understand (all fields optional):

---
id: my-project
type: project
tags: [dev]
status: active
summary_l0: "One-line summary shown in list_brain."
updated: 2026-07-07
---

# My project
Links to other files as [[people/jane-doe]] wiki-links → graph edges.

Setup

Prereqs: Node 18+, a Cloudflare account (free), a GitHub account.

1. Install

npm install
npm --prefix app install

2. Configure your identity

Edit the vars block in wrangler.jsonc:

3. Create a GitHub OAuth App (login / identity)

GitHub → Settings → Developer settings → OAuth Apps → New OAuth App.

• Homepage URL: your future worker URL, e.g. https://brain-mcp.<your-subdomain>.workers.dev

• Authorization callback URL: the Worker's own callback — https://brain-mcp.<your-subdomain>.workers.dev/callback

Architecture note: the Worker is its own OAuth 2.1 server for claude.ai; GitHub is only the upstream login. So GitHub redirects back to the Worker's /callback, and that is the only callback GitHub needs. claude.ai registers its own redirect URIs with the Worker automatically via dynamic client registration (/register). You won't know the exact workers.dev subdomain until the first deploy — deploy once with a placeholder, then come back and set the real URL.

Copy the Client ID and generate a Client secret.

4. Create the fine-grained PAT (repo read/write)

GitHub → Settings → Developer settings → Fine-grained tokens → Generate new token.

• Repository access: Only select repositories → your brain repo

• Permissions: Contents = Read and write (Metadata = Read is added automatically)

5. Cloudflare: KV + secrets

npx wrangler login
npx wrangler kv namespace create OAUTH_KV
# paste the printed id into wrangler.jsonc (REPLACE_WITH_KV_ID)

npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put GITHUB_BRAIN_TOKEN

6. Build the app & deploy

npm --prefix app run build
npx wrangler deploy

Your MCP endpoint is the printed URL + /mcp. If your OAuth App used a placeholder host, update its Homepage/callback URLs to the real one now.

app/public/ ships placeholder icons (favicon.svg, icon-192.png, icon-512.png): a neutral little graph, no branding. They are there because a PWA without icons doesn't install, which would break the phone capture and the share target. Replace the three files with your own and rebuild — the filenames are referenced from app/index.html and both manifests, so keeping the names means nothing else to change.

7. Connect

• claude.ai → Settings → Connectors → Add custom connector → paste the /mcp URL → Connect → log in with GitHub. Anyone who isn't ALLOWED_LOGIN gets a 403.

• Browser cockpit → open the worker URL → "Se connecter avec GitHub".

• Phone → open the worker URL in mobile Chrome/Safari, log in once (the session cookie lasts 30 days), then use the browser's Install / Add to home screen. Long-pressing the installed icon exposes the Nouvelle idée shortcut; installing from /capture directly gives you a second icon that opens straight into the capture box.

8. Smoke test

1. In a new chat: "list my brain" → file map with summaries.

2. "read my now.md" → file content.

3. "add a test decision: validated the MCP write path" → appends to decisions/YYYY-MM.md; confirm the commit on GitHub.

4. Open /capture, type anything, send → a new line in inbox/idees-<today>.md on GitHub. Turn airplane mode on and send another one: it stays queued and leaves as soon as the network is back.

Triaging what you capture

Capture is deliberately dumb, so inbox/ fills up with day-files. Emptying them is a separate session, and Claude does the work through the same MCP tools: "read inbox/idees-2026-08-15.md, ask me about anything ambiguous, then file each line where it belongs and delete the inbox file". Nothing classifies on its own — an idea filed by guesswork is worse than an idea left in the inbox.

Local development

cp .dev.vars.example .dev.vars   # fill in the three secrets
npx wrangler dev

UI-only work doesn't need any of that: npm --prefix app run dev then open /mock.html — the API is stubbed with plausible fake data (app/src/dev-mock.ts).

Security model

See SECURITY.md for the full threat model. Short version: the worker URL is public but serves nothing without a valid GitHub-verified session; a single ALLOWED_LOGIN gate covers both surfaces (MCP + browser); the repo PAT lives only in Worker secrets; every write goes through secret detection and folder guards; rendered markdown is sanitized against stored XSS. Disaster recovery (lost Cloudflare account, etc.) is covered in RECOVERY.md — worst case degrades to a folder of readable markdown, never to nothing.

License

MIT.