second-brain-mcp

A minimal MCP server that lets any Claude client — iPhone, web, desktop — write to your GitHub-backed markdown vault directly, not just whatever agent happens to be running locally.

Two tools, nothing else:

• capture(text, actionable=False) — appends a bullet to your inbox file's capture section. No frontmatter, no filing decision, no question asked — zero-friction capture from wherever you're chatting.

• read_file(path) — reads any file in the vault repo (your INDEX.md, an AGENTS.md, a note) so Claude can pull context on demand instead of guessing.

Both go through the GitHub Contents API, so the vault stays plain git — no database, no extra service to run besides this one.

Why

If your vault lives in a local git repo and your agent only runs on your laptop, capture only works when you're at your laptop. This closes that gap: deploy it once, connect it to Claude as a custom connector, and capture works from any device signed into your account.

Related MCP server: clawmemory-mcp

Requirements

• A git repo (GitHub) holding your markdown vault, with an inbox file that has a heading (default ## To process) followed by a bullet list ending in a trailing empty - bullet. This matches the convention from killian31/second_brain_template — if your vault was bootstrapped from that template, this works out of the box.

• Somewhere to run a container with a public HTTPS URL. These instructions use Google Cloud Run (free tier comfortably covers personal use at min-instances=0), but any host that can run the Dockerfile works.

• Python 3.11+ (only to generate a token locally; the server itself just needs a container host).

Setup

1. Fork or clone this repo

2. Create a GitHub fine-grained personal access token

Go to github.com/settings/personal-access-tokens/new:

• Resource owner: your account

• Repository access: Only select repositories → your vault repo

• Permissions → Repository permissions → Contents: Read and write

• Generate, copy the value (github_pat_...)

Fine-grained PATs require an expiration date and don't have a gh/API creation path — this step is manual by design on GitHub's end.

3. Generate a bearer token

This is the credential Claude will send on every request. Generate one yourself, don't reuse anything else:

python3 -c "import secrets; print(secrets.token_urlsafe(32), end='')"

4. Deploy

Example with Cloud Run (adjust PROJECT/REGION to yours):

gcloud secrets create second-brain-mcp-github-token --data-file=- <<< "github_pat_xxx"
gcloud secrets create second-brain-mcp-bearer-token --data-file=- <<< "your-generated-token"

gcloud run deploy second-brain-mcp \
  --project PROJECT --region REGION --source . \
  --min-instances=0 --max-instances=1 --allow-unauthenticated \
  --set-secrets=GITHUB_TOKEN=second-brain-mcp-github-token:latest,BEARER_TOKEN=second-brain-mcp-bearer-token:latest \
  --set-env-vars=GITHUB_REPO=your-username/your-vault-repo

--data-file=- <<< writes the secret from stdin with no trailing newline — don't pipe in a value from echo or print() without stripping the newline, or the bearer check will never match (see Gotchas below).

The default compute service account needs roles/secretmanager.secretAccessor on both secrets:

gcloud secrets add-iam-policy-binding second-brain-mcp-github-token \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"
# repeat for second-brain-mcp-bearer-token

5. Connect it to Claude

In the Claude app: Settings → Connectors → Add custom connector

• Server URL: https://your-service-url/mcp

• Authentication: No sign-in

• Open Request headers → add header, name Authorization, value Bearer your-generated-token, mark Required

The Request headers option is a beta Anthropic feature and may not be available on every account yet. If you don't see it, you're limited to OAuth for now — this server doesn't implement that (see Limitations).

Test it: ask Claude to capture something, then check your inbox file.

Environment variables

Gotchas (hit these during the first deploy, saving you the time)

• Trailing newlines break the bearer check. python3 -c "print(...)" or echo add a \n that ends up baked into the secret, and Authorization header comparison is an exact string match. Use print(..., end='') or printf '%s'.

• The MCP SDK's DNS-rebinding protection rejects your own Cloud Run hostname by default. It's meant for browser-reachable local servers; this is a server-to-server API with no browser in the loop, so app.py explicitly disables it (TransportSecuritySettings(enable_dns_rebinding_protection=False)). If you fork this and see 421 Invalid Host header, that's why.

• The GitHub Contents API caps out around 1MB per file. Fine for notes, not for anything you'd embed as binary.

Limitations

• Auth is a single static bearer token, not OAuth — anyone with the token can call capture/read_file on your repo. Fine for solo/small-group personal use; rotate the token (new secret version + redeploy) if it leaks.

• No write access outside INBOX_PATH — by design. This is meant to stay a dumb capture tool, not reinvent note-filing.

• read_file has no directory recursion or search — point your agent at an INDEX.md or similar in your vault for that.

License

MIT — see LICENSE.