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.

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

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

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.