# gmail-mcp

A multi-account Gmail [MCP](https://modelcontextprotocol.io) server for AI agents
(Claude Code and anything else that speaks MCP), with one design goal above all:
**the agent can read and draft freely, but a human must approve every send.**

Built because the hosted Gmail connectors bind one account at a time and send
without friction. This server binds any number of Gmail accounts behind short
aliases (`work`, `school`, ...) and splits capabilities by risk:

| Capability | Who can do it |
|---|---|
| Search, read threads, list drafts | Agent, freely |
| Create and update drafts | Agent, freely |
| **Send** | Only with a single-use approval token a human mints in a terminal |

The server is registered as `gmail-accounts` (not `gmail`) on purpose: if you also
run a hosted Gmail connector, near-identical tool names make an agent read the
wrong mailbox and report a confident false negative.

## How the send gate works

1. The agent stages a draft and asks you to approve it.
2. You run `gmail-approve` in your own terminal, review the exact RFC822 payload,
   and get a one-time token bound to that draft's content hash.
3. The agent calls the send tool with the token. Wrong draft, edited draft, reused
   token, expired token: all refused.

The send tool also carries `anthropic/requiresUserInteraction`, so Claude Code
prompts a human even in `bypassPermissions` mode. The token CLI is a mistake
interlock; the harness prompt is the enforced boundary.

## Setup

Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).

### 1. Google Cloud OAuth client

Create a project at console.cloud.google.com, enable the Gmail API, create an
**OAuth client ID of type Desktop app**, and download the JSON to:

```
~/.config/gmail-mcp/client_secret.json
```

### 2. Declare your accounts

`~/.config/gmail-mcp/accounts.json`:

```json
{
  "accounts": [
    { "alias": "personal", "email": "alice.personal@gmail.com" },
    { "alias": "work",     "email": "alice.work@gmail.com" }
  ]
}
```

Adding an account later is a config edit plus one auth run; the file is re-read on
every call, so no restart is needed.

### 3. Authorize each account

```bash
uv sync
scripts/auth-all.sh          # runs the OAuth flow once per alias, skips done ones
```

Each grant is verified against its alias: authorizing the wrong Google account in
the browser is detected and refused, not silently stored.

### 4. Register with Claude Code

```bash
claude mcp add gmail-accounts -- uv run --directory /path/to/gmail-mcp --frozen --no-sync gmail-mcp
```

## Everyday use

Every tool takes an `account` alias. Ask the agent things like "search work for
the invoice thread" or "draft a reply on personal". When it is time to send:

```bash
gmail-approve            # lists pending sends, shows the payload, mints a token
```

Health check:

```bash
uv run gmail-mcp-health
```

## Security notes

- Secrets never enter the repo: `client_secret.json` and per-account tokens live
  in `~/.config/gmail-mcp/` (override with `GMAIL_MCP_CONFIG`).
- All config writes are atomic (tmp + fsync + rename); a crash mid-write never
  leaves a torn file.
- stdout is the JSON-RPC channel; nothing in the package may `print()` (enforced
  by ruff T201), so diagnostics cannot corrupt the protocol.

## Tests

```bash
uv run pytest
```