# mcpbrain

mcpbrain is a local-first personal knowledge daemon. It syncs your Gmail and Drive (and Calendar, if you grant it) into a SQLite store on your own machine, embeds the text for search, and serves it to Claude Desktop over MCP. You then ask Claude things like "search my brain for the campus budget", "what's the context on this person", or "who's connected to this project", and it answers from your own mail and docs, including the relationships between the people and projects it finds.

Everything stays on your laptop. Nothing is sent anywhere unless you turn on the optional encrypted backup, or you query Claude Desktop (in which case Claude Desktop sends your query to Anthropic, same as any other Claude chat).

> Maintainers: see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the system overview (daemon, MCP connector, distribution topology), [`docs/DISTRIBUTION.md`](docs/DISTRIBUTION.md) for the update channel, and [`docs/RELEASE-RUNBOOK.md`](docs/RELEASE-RUNBOOK.md) for release steps.

## Install

mcpbrain installs as a Claude Code plugin. In a Claude Code session, run:

```
/mcpbrain:install
```

and follow it — it installs the daemon, connects it to Claude, opens the sign-in
wizard, and creates the recurring background tasks for you.

On a machine that does not have the plugin yet, install it from the organisation
plugin catalogue in the Claude app:

1. Open **Customize** in the left sidebar.
2. Open the **Plugins** tab.
3. Click **Browse plugins**.
4. Filter by **Centrepoint Church**.
5. Click **Install** on the mcpbrain plugin.

then run `/mcpbrain:install`.

The plugin is distributed through claude.ai **organization settings**, which is why
`Centrepoint-Church/mcpbrain-plugin` is a private repo — org sync requires the
marketplace repository to be private or internal, and it packages the plugin for
each user, so nobody needs access to that repo. Updates arrive through org sync.
`claude plugin marketplace add` is NOT the supported path here: it would need each
person to hold git credentials for a private repo, and background refreshes disable
credential helpers, which silently pins them to whatever they first cloned. The full walkthrough — the Windows path, what to
expect at each step, and the manual fallback for the recurring tasks — is in
[`plugin/INSTALL.md`](plugin/INSTALL.md); the actual install command is written
once, in [`plugin/commands/install.md`](plugin/commands/install.md), and every
other doc points at it rather than repeating it.

Setting mcpbrain up for a different organisation? See [docs/FORKING.md](docs/FORKING.md).

### What the install does

1. Installs `uv` if it isn't already on the machine.
2. Installs the `mcpbrain` CLI as a `uv` tool.
3. Registers a login agent so the daemon starts when you log in (launchd on macOS, a systemd user service on Linux, a scheduled task on Windows).
4. Registers mcpbrain with Claude Desktop and opens a browser wizard to connect your Google account.
5. Creates the four recurring `brain_*` background tasks as Local scheduled tasks.

In the wizard you sign in with your own Google account and grant read-only access to Gmail, Drive, and (optionally) Calendar. You don't create a Google Cloud project; mcpbrain ships a shared OAuth client (see the maintainer notes below). Because the app isn't through Google's verification yet, the browser shows "Google hasn't verified this app". Click Advanced, then continue. The token is written to your local data directory and the daemon picks it up.

The wizard's last step, **"Connect & restart Claude Desktop,"** quits and reopens Claude Desktop for you in one click, after which the `brain_search`, `brain_read`, `brain_context`, and `brain_graph` tools are available in any chat.

## Updating

```bash
mcpbrain update
```

This checks the wheel index for a newer published version and, if there is one,
reinstalls mcpbrain via uv and restarts the login agent so the new code takes
effect. Installed daemons also do this on their own about once a day, so running
it by hand is only for pulling a release early. It never touches your store, your
config, or your Google token.

## What runs at login

The login agent starts the mcpbrain daemon in the background. The daemon runs a loop: it syncs new mail and docs into the local store, embeds them for search, and (if you've set a Gemini key) extracts the entity/relationship graph that powers `brain_context` and `brain_graph`. Run only one daemon at a time; it holds a single-writer lock on the store. Claude Desktop opens the store read-only, so it's safe alongside the daemon.

A second, optional login agent runs a menu-bar tray (`mcpbrain tray`). It shows whether the daemon is running or paused and how many items are indexed, and gives you Pause/Resume, Open setup, and Quit. The tray is a status-and-control client that talks to the daemon over the loopback control API; it does not own the daemon, so quitting the icon closes the menu bar item only and leaves syncing running. It comes back at your next login, or run `mcpbrain tray` to relaunch it.

## What leaves your machine

Two things, and only these:

1. The encrypted backup, if you enable it. Backup is off by default. When configured, it snapshots the derived store, encrypts it with an org-held escrow key, and uploads it to a per-user folder on a Shared Drive. The backup contains your synced mail and doc text, encrypted; only a holder of the escrow key can decrypt it.
2. Whatever Claude Desktop sends to Anthropic when you query. That's the normal Claude Desktop data path, not something mcpbrain adds.

The sync, the store, the embeddings, and the knowledge graph all stay local.

## Trust model

This is an unsigned, clone-and-run tool shared from a private repo with invited collaborators. There's no notarised binary and no app-store review between you and the code. You were invited because someone trusts you with it; you read the repo, decide to trust it, and run it. If that isn't acceptable for your machine, don't run it.

## For the maintainer: provision the shared OAuth client

Done once by the maintainer, not by each user. It creates the one OAuth client the app embeds.

1. In the Google Cloud Console, create or pick a project.
2. OAuth consent screen: User type External. Add the app name, your support and developer email, and the scopes `gmail.readonly`, `calendar.readonly`, `drive.readonly`. Save. Leave it in Testing (with test users) or publish it to "In production" unverified.
3. Credentials → Create credentials → OAuth client ID → Application type: Desktop app. Download the JSON.
4. Put it at `mcpbrain/google_oauth_client.json` (the bundled path; it's gitignored so the real client isn't committed). A desktop client's secret is non-confidential by Google's design because the flow uses PKCE, so bundling it with the app is the standard, accepted practice.

Until this file exists, the auth step raises a clear error (or falls back to a user-supplied client secret).

## Verification and the user cap

The app is shared privately with invited collaborators, who sign in as Google "test users" on the unverified consent screen. That model needs no verification and no security assessment:

- An unverified app allows about 100 test users, and each one sees the "unverified app → Advanced → Continue" warning. A collaborator set sits well inside that.
- It costs nothing.

Verification only matters if you later open the app to the general public. Because Gmail and Drive read are restricted scopes, public verification also requires an annual third-party CASA security assessment, which is a real recurring cost, so it's a deliberate business decision rather than a code change. Narrowing Drive to the non-restricted `drive.file` scope would avoid the Drive assessment, but it loses access to your existing Drive files, so it isn't suitable here.

## Licence

See `LICENSE`. The licence is a placeholder (MIT) pending confirmation.