personal-brain-mcp

A serious second brain for your personal life, exposed as a Model Context Protocol server. Drop it into Claude Desktop, Cursor, n8n, or any MCP client and ask your own life questions.

Claude Desktop / Cursor / n8n / your own agents
                │
                │  HTTPS + SSE + Bearer token
                ▼
        Cloudflare Worker  ◄────  iPhone Shortcuts (capture, health)
        (this repo)        ◄────  Telegram / Discord bots (chat capture)
                │
                │  Postgres + pgvector (service role)
                ▼
              Supabase
        (schema: brain)

What it is

A personal-life database with 47 tools + 4 HTTP ingest endpoints + inbound chat bots across 13 domains, with semantic search, hybrid retrieval (vector + keyword), and a four-layer memory model.

You stand it up once, then use it from any MCP-aware AI client. It's your brain; you own the data; it runs on free tiers.

Domains covered

Full catalog: TOOLS.md.

Related MCP server: agentbay-mcp

Why this exists

• Memory you control. No vendor lock-in. The brain is just Postgres rows you can dump anytime.

• One brain, many clients. Same data accessible from every AI client that speaks MCP.

• Cheap. Cloudflare Workers free tier + Supabase free tier + ~$0.50/mo for OpenAI embeddings.

• Opinionated. Schema and tools designed for a real personal life, not a generic note-taking app.

Quick start

If you know what you're doing:

git clone https://github.com/YOUR_GITHUB_USER/personal-brain-mcp.git
cd personal-brain-mcp
npm install
cp .dev.vars.example .dev.vars     # fill in real values
supabase link --project-ref <ref>
supabase db push
wrangler dev

If you want guidance, read SETUP.md. It walks the whole flow with the why behind each step.

Documentation

Stack

• Cloudflare Workers — Worker + Cron Triggers (free tier handles personal use easily)

• Supabase — Postgres + pgvector + RLS (free tier works for one user; upgrade for backups)

• OpenAI — text-embedding-3-small for semantic search

• TypeScript + MCP SDK + Zod — server-side

• @supabase/supabase-js — typed DB client

What this is NOT

• Not a calendar. Use your existing calendar (Google, Outlook, etc.). This brain has a query_external_data tool that points the LLM to your calendar connector when needed.

• Not an email client. Same as calendar.

• Not a balance tracker. It tracks which accounts exist, not balances. Use Plaid / your bank's portal for balances.

• Not a habit tracker. Use TickTick, Habitica, Streaks, etc. — they're better at habits than a Postgres row would be.

• Not for business data. Build a second MCP server for business context (the architecture supports this — just use a different Supabase schema like org_a and a separate Worker).

Architecture decisions worth understanding before you fork

• MCP as the access layer, not the storage. The brain is just Postgres. MCP tools are the read/write API. You can always query the DB directly.

• Service role from the Worker. RLS is enabled but no policies; the Worker is the trust boundary. Single-user assumption baked in. If you want multi-tenant, write proper RLS policies before deploying.

• Append-immutable facts. Layer-4 facts use superseded_by chains. Old values are preserved.

• Hybrid retrieval. ask_brain combines vector similarity with pg_trgm keyword match. Both contribute.

• Source-agnostic chat capture. Adding a new platform = one adapter file. iMessage and Signal are explicitly NOT supported (see bots/README.md for reasoning).

Origin and credit

Inspired in part by Friday (a 24/7 assistant built on Claude Code), particularly its proactive-messaging pattern, control-plane-as-prompt approach, and hybrid retrieval. Architecture diverges where MCP-as-server and pgvector-as-store are the better fit.

License

MIT. See LICENSE.

Contributing

PRs welcome for:

• Additional ingest sources (WhatsApp implementation, Slack, etc.)

• Additional MCP clients beyond Claude Desktop

• Schema or tool improvements that stay generic

• More iPhone / Android Shortcuts patterns

Not welcome:

• Personal-flavor changes (your spouse's name as the default test value, etc.)

• Locking the design to a single LLM vendor

• Bundling external dependencies that aren't justified

If your fork diverges significantly from "personal life brain," that's great — give it a different name and link back. This project will stay opinionated about scope.