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

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.

Related MCP server: gmail-mcp-local

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

[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

Development

npm install
npm run check
npm run secret-scan

See SECURITY.md, docs/THREAT_MODEL.md, and 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.