Multi-Account Gmail — Claude Code MCP server: many inboxes
An MCP server that keeps several Gmail accounts authorized at once, so your agent can read, search, label and draft across all of them.
claude mcp add --env GMAIL_MCP_CLIENT_SECRET=<GMAIL_MCP_CLIENT_SECRET> --env GMAIL_MCP_DB=<GMAIL_MCP_DB> --env GMAIL_MCP_OAUTH_PORT=<GMAIL_MCP_OAUTH_PORT> --transport stdio multi-account-gmail -- uvx multi-account-gmail-mcpWhat Multi-Account Gmail does
Most Gmail connectors tie one mailbox to one OAuth grant. Connect a second address and the first stops working. This server takes a different route: a single Google Cloud client authorizes any number of accounts, each one saved as a record in a local SQLite file, and every tool accepts an account argument that picks the mailbox. The search_all_accounts tool queries all of them in one pass and tags each hit with its account.
It runs over stdio. Tokens sit in one file under ~/.gmail-mcp/, which you can copy, open in any SQLite viewer, or edit to revoke an account. Four narrow scopes are requested — gmail.readonly, gmail.compose, gmail.modify, gmail.settings.basic — never full mailbox access. Sending is out of scope by design: create_draft leaves a draft behind and you send it yourself.
You need Python 3.12+ and a client_secret.json from a Google Cloud project. Auth assumes the machine may have no browser: the CLI prints a consent link, listens on a fixed port, and you forward the redirect over SSH. That port comes from GMAIL_MCP_OAUTH_PORT; if something else already holds it, the login will not finish.
What it helps with
- find an invoice email across every connected inbox
- pull a full thread by its id
- save a message's attachments to disk and get their paths
- clear the INBOX label from a batch matched by a query
- count matches before a bulk change so nothing extra gets touched
Example prompts for the agent
- Search all accounts for messages with "invoice" from the last 30 days
- Read thread
19a...in the work account and summarize what was agreed - Draft a reply to message
18f...saying the payment has gone out
How to install Multi-Account Gmail
Platform CLI
claude mcp add --env GMAIL_MCP_CLIENT_SECRET=<GMAIL_MCP_CLIENT_SECRET> --env GMAIL_MCP_DB=<GMAIL_MCP_DB> --env GMAIL_MCP_OAUTH_PORT=<GMAIL_MCP_OAUTH_PORT> --transport stdio multi-account-gmail -- uvx multi-account-gmail-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from multi-account-gmail-mcp <command>
Platform CLI
codex mcp add multi-account-gmail --env GMAIL_MCP_CLIENT_SECRET=<GMAIL_MCP_CLIENT_SECRET> --env GMAIL_MCP_DB=<GMAIL_MCP_DB> --env GMAIL_MCP_OAUTH_PORT=<GMAIL_MCP_OAUTH_PORT> -- uvx multi-account-gmail-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from multi-account-gmail-mcp <command>
Config file
{
"mcpServers": {
"multi-account-gmail": {
"command": "uvx",
"args": [
"multi-account-gmail-mcp"
],
"env": {
"GMAIL_MCP_CLIENT_SECRET": "<GMAIL_MCP_CLIENT_SECRET>",
"GMAIL_MCP_DB": "<GMAIL_MCP_DB>",
"GMAIL_MCP_OAUTH_PORT": "<GMAIL_MCP_OAUTH_PORT>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from multi-account-gmail-mcp <command>
Config file
{
"servers": {
"multi-account-gmail": {
"type": "stdio",
"command": "uvx",
"args": [
"multi-account-gmail-mcp"
],
"env": {
"GMAIL_MCP_CLIENT_SECRET": "<GMAIL_MCP_CLIENT_SECRET>",
"GMAIL_MCP_DB": "<GMAIL_MCP_DB>",
"GMAIL_MCP_OAUTH_PORT": "<GMAIL_MCP_OAUTH_PORT>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from multi-account-gmail-mcp <command>
Platform CLI
gemini mcp add -e GMAIL_MCP_CLIENT_SECRET=<GMAIL_MCP_CLIENT_SECRET> -e GMAIL_MCP_DB=<GMAIL_MCP_DB> -e GMAIL_MCP_OAUTH_PORT=<GMAIL_MCP_OAUTH_PORT> multi-account-gmail uvx multi-account-gmail-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from multi-account-gmail-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Multi-Account Gmail
How do I install Multi-Account Gmail in Claude Code?
Run claude mcp add multi-account-gmail-mcp -- uvx multi-account-gmail-mcp. To pass environment variables, use the longer form: `claude mcp add --env GMAIL_MCP_CLIENT_SECRET=<GMAIL_MCP_CLIENT_SECRET> --env GMAIL_MCP_DB=<GMAIL_MCP_DB> --env GMAIL_MCP_OAUTH_PORT=<GMAIL_MCP_OAUTH_PORT> --transport stdio multi-account-gmail -- uvx multi-account-gmail-mcp`.
What does Multi-Account Gmail do?
It reads, searches, labels and drafts across several Gmail mailboxes from one connection. It does not send mail — the draft is left for you.
How is it different from the standard Gmail connector?
The standard connector binds one account per OAuth grant. Here you can authorize as many as you like, and one search can cover all of them.
