gmail-multi-mcp

Connect multiple Gmail accounts to Claude (or any MCP client) from one local server. The official Gmail connector only supports a single Google account — this lets you search, read, draft, send, label, and organize mail across as many accounts as you like, each addressed by a friendly alias.

Your OAuth tokens are stored locally on your machine only — never uploaded anywhere.

Features

• 🔢 Unlimited accounts — every tool takes an account parameter ("personal", "work", …)
• 🔎 Search & read — full Gmail search syntax, thread/message reading, attachment download
• ✍️ Compose — create/list/delete drafts, send mail, replies with correct threading headers
• 🏷️ Organize — full label management, archive, trash
• 🔐 Local-first — standard Google OAuth; tokens live in ~/.gmail-mcp/, chmod 600
• 🧩 22 tools, works with Claude Code, Claude Desktop, Cursor, and any MCP client

Prerequisites

• Node.js ≥ 20
• A Google account (and a free Google Cloud project — setup below)

1. Install

git clone https://github.com/Vinksj/claude-gmail-multi.git
cd claude-gmail-multi
npm install
npm run build

2. Create your Google OAuth app (one-time, ~10 min)

You register one OAuth "app" with Google; it then works for all the accounts you connect.

1. Go to console.cloud.google.com → create a project (e.g. gmail-mcp).
2. APIs & Services → Library → search Gmail API → Enable.
3. APIs & Services → OAuth consent screen:
   • User type External → Create.
   • App name + your support email + your contact email → Save and Continue.
   • Scopes page → Save and Continue. Test users page → Save and Continue.
4. Publish to production: on the OAuth consent screen, set Publishing status → Publish app. (In "Testing" mode Google expires your refresh token every 7 days. Publishing avoids that. You'll click through a one-time "Google hasn't verified this app" warning per account — that's normal for a personal app: choose Advanced → Continue.)
5. APIs & Services → Credentials → Create Credentials → OAuth client ID:
   • Application type Desktop app → Create → Download JSON.
6. Save that file as ~/.gmail-mcp/credentials.json:

   mkdir -p ~/.gmail-mcp && chmod 700 ~/.gmail-mcp
   mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json
   chmod 600 ~/.gmail-mcp/credentials.json
   

Note: newer Google Cloud UIs put these under "Google Auth Platform" (Branding / Audience / Clients) instead of "OAuth consent screen" — same steps, different labels.

3. Connect your accounts

npm run auth -- --alias personal --email you@gmail.com
npm run auth -- --alias work --email you@company.com

Each opens a browser → pick the matching Google account → approve. The optional --email flag aborts if the wrong account gets authorized (an easy mistake with multi-login browsers). Connect as many as you want; re-run any time a token is revoked.

4. Register with your MCP client

Claude Code:

claude mcp add --scope user gmail-multi -- node "$(pwd)/dist/index.js"

Claude Desktop / other clients — add to your MCP config:

{
  "mcpServers": {
    "gmail-multi": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-multi-mcp/dist/index.js"]
    }
  }
}

Tools appear as gmail-multi's search_threads, create_draft, etc. Ask things like "search my work inbox for unread from this week" or "draft a reply in personal to Alice."

Tools

Group	Tools
Accounts	list_accounts, add_account
Read	search_threads, get_thread, get_message, download_attachment
Compose	create_draft, list_drafts, delete_draft, send_draft, send_message
Labels	list_labels, create_label, update_label, delete_label, label_thread, unlabel_thread, label_message, unlabel_message
Cleanup	archive_thread, trash_thread, trash_message

Every tool except list_accounts takes an account parameter (alias or email). Replies via replyToMessageId get correct In-Reply-To/References headers and threading automatically.

How it works

• One self-owned Google Cloud OAuth app (Desktop client) authorizes any number of accounts.
• Single scope: https://www.googleapis.com/auth/gmail.modify (read, search, drafts, send, labels, archive, trash — narrower than full https://mail.google.com/).
• Per-account refresh tokens stored in ~/.gmail-mcp/tokens/<alias>.json (chmod 600); the account registry is ~/.gmail-mcp/config.json. Nothing leaves your machine.

~/.gmail-mcp/
├── credentials.json        # your OAuth client (you add this)
├── config.json             # alias → email map (auto-managed)
└── tokens/<alias>.json     # per-account refresh tokens (auto-managed)

Security notes

• Tokens are stored as plain files readable only by your user (chmod 600). On a single-user machine with full-disk encryption this is reasonable; moving token storage to the OS keychain is a sensible future hardening step.
• Never commit ~/.gmail-mcp/ — it lives in your home directory, outside this repo, and the repo's .gitignore excludes build artifacts and dependencies regardless.
• The gmail.modify scope cannot permanently delete mail — trash_* tools move items to Trash (recoverable for 30 days).

Development

npm run build      # tsc -> dist/
npm run inspect    # MCP Inspector UI against the built server
npm run auth -- --alias <name> [--email <expected>]

Important: stdout is the JSON-RPC channel — never console.log in server code; use console.error.

License

MIT © Saurabh Jain