# Multi-Account Gmail MCP

An experimental v0.1.0, local-first TypeScript MCP server that keeps multiple Gmail OAuth grants separate and requires an explicit account alias for drafts and mailbox changes.

This project is intended for one person running it on their own computer. Hosted or multi-user deployment is outside the v0.1.0 security model.

## Architecture

```mermaid
flowchart TD
  C["Codex or MCP client"] --> S["Multi-Account Gmail MCP"]
  subgraph L["Local trust boundary"]
    S --> R["Account router"]
    R --> A1["personal"]
    R --> A2["work"]
    S --> G["Gmail service"]
    S --> V["Credential-store interface"]
    V --> K["OS credential vault"]
    V -. explicit fallback .-> E["AES-256-GCM local vault"]
    G --> P["Safety policy"]
  end
  A1 --> G
  A2 --> G
  K --> G
  E --> G
  P --> API["Gmail API"]
```

Every operation resolves one account record before its credential is loaded. Stored grants are keyed by a stable hash of the Google-verified Gmail address; aliases never select credentials directly.

## Setup

1. Create your own Google Cloud project, enable the Gmail API, configure an OAuth consent screen, and create your own **Desktop app** OAuth client. Never reuse credentials supplied by another user or repository. Add every Gmail address you will connect as a test user while the consent screen is in testing mode.
2. Run `npm install`, then `npm run setup:local`. This creates an ignored `.env` with a fresh encryption key. Add your own OAuth client ID and client secret to its first two lines, or run `npm run setup:google -- /path/to/your-downloaded-client-secret.json`. Do not commit `.env` or downloaded client-secret JSON.
3. Run `npm run build`, then `npm start`.
4. Ask the MCP client to call `start_account_authorization` with an alias such as `personal`. Open the returned URL and finish Google consent.
5. Repeat with another alias. Use `set_default_account` for read-only operations; drafts and mutations always require `account` explicitly.

By default, the server uses stdio for MCP and listens only on `127.0.0.1` for OAuth callbacks. Set `GMAIL_MCP_TRANSPORT=http` for a local Streamable HTTP endpoint at `/mcp`.

### Codex configuration

```toml
[mcp_servers.multi-account-gmail]
command = "node"
args = ["--env-file=/absolute/path/to/multi-account-gmail-mcp/.env", "/absolute/path/to/multi-account-gmail-mcp/dist/index.js"]
```

Restart Codex after changing MCP configuration.

## Tools

| Area | Tools | Status |
|---|---|---|
| Accounts | `list_accounts`, `start_account_authorization`, `disconnect_account`, `set_default_account` | Implemented |
| Standard retrieval | `search`, `fetch` | Implemented |
| Mail reads | `get_profile`, `list_labels`, `search_messages`, `get_message`, `get_thread` | Implemented |
| Attachments | `list_attachments`, `fetch_attachment` | Implemented; fetch returns base64 for local materialization |
| Organization | `set_message_labels` | Implemented; covers archive and read state through system labels |
| Drafts | `create_draft` | Implemented |
| Direct send/reply/forward | — | Intentionally deferred until approval and confirmation UX is validated |
| Trash/bulk destructive changes | — | Intentionally deferred |

## Development

```sh
npm install
npm run check
npm run secret-scan
```

See [SECURITY.md](SECURITY.md), [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md), and [docs/PRIVACY.md](docs/PRIVACY.md).

## Current limitations

- v0.1.0 is experimental, single-user, and local-first; it is not a hosted or multi-tenant service.
- Gmail OAuth apps in testing mode and sensitive scopes are subject to Google limitations and verification rules.
- HTML-only mail falls back to decoded source text; rich HTML sanitization is not included.
- Attachments are returned as base64 because local MCP hosts differ in file-reference support.