Multi-Account Gmail

gmail-mcp

An [MCP](https://modelcontextprotocol.io) server that reads across _all_ your Gmail accounts from one connection.

Most Gmail integrations — including the native connectors — bind a single account per OAuth grant: connect a second inbox and you disconnect the first. gmail-mcp keeps any number of accounts authorized at once. One Google Cloud client authorizes them all, each lands as a row in a local SQLite file, and every tool takes an account argument that routes to the right mailbox. search_all_accounts sweeps all of them in a single query.

Python 3.12+ · MIT · stdio MCP server + auth CLI · local SQLite token store

It's built to be owned completely: runs in-process over stdio, stores tokens in one SQLite file you can inspect, copy, or delete, talks only to Google and your MCP client, and hardcodes no secrets.

It reads, searches, drafts, and labels. It doesn't send — create_draft leaves a draft for you to send yourself. That's a deliberate default (reasoning in Security model), not a hard stance; if you want autonomous send, it's a small addition or a different server.

---

Contents

• The idea in 30 seconds
• Design notes
• Tools
• Architecture
• Identity & auth model
• The OAuth model
• The multi-account model
• Token lifecycle
• The headless auth path
• Security model
• Install
• Quickstart
• Configuration
• Register with an MCP client
• Development
• Project layout
• License

---

The idea in 30 seconds

Authorize N accounts once via the CLI. Then every tool takes an account, and search_all_accounts hits all of them at once:

search_all_accounts(query="invoice newer_than:30d")

── personal@gmail.com ─────────────────────────────── from: billing@acme.com subject: Invoice #4821 (id 18f...)

── work@company.com ───────────────────────────────── from: ap@vendor.io subject: March invoice (id 19a...)

One query, every inbox, each result tagged with its account and carrying the message id — so the agent can chain read_message(account, id) or create_draft(...) next.

---

Design notes

One OAuth client, many inboxes. A single Google Cloud project and one client_secret.json authorize every account. Adding the tenth inbox is the same one-command flow as the first.

Boring storage. Tokens live in one SQLite file under ~/.gmail-mcp/. No daemon, no keyring dependency, no cloud. Back it up by copying it; revoke an account by deleting a row; inspect it with any SQLite tool.

Least privilege. Four granular scopes — gmail.readonly, gmail.compose, gmail.modify, gmail.settings.basic — never the full-mailbox https://mail.google.com/. It can read, draft, label, and manage filters; it never sends mail, and filters it creates can't forward mail off-account.

Headless-friendly. The auth flow assumes the server may have no browser: it prints a consent URL, binds a fixed port, and you SSH-forward the redirect. Works fine on a desktop too.

---

Tools

Every tool except list_accounts and search_all_accounts takes an account (the email address). Unknown accounts return an error listing the authorized ones.

---

Architecture

flowchart TD

subgraph client[Your machine] Agent[MCP client / agent] CLI[gmail-mcp-auth CLI] Server[gmail-mcp stdio server] Store[("SQLite ~/.gmail-mcp/tokens.db")] Secret["client_secret.json one OAuth client"] end Google[Google OAuth + Gmail API]

CLI -->|"loopback OAuth, once per account"| Google CLI -->|"store refresh token"| Store Secret -.-> CLI Agent -->|"tool call (account=...)"| Server Server -->|"look up + refresh creds"| Store Secret -.-> Server Server -->|"read / draft / label"| Google Server --> Agent

Authorization happens once per account through the CLI (it needs a browser). After that the stdio server reads tokens straight from SQLite, refreshing access tokens on demand and persisting them back. The rest of this section is the "why it works the way it does" detail.

---

Identity & auth model

How gmail-mcp authenticates to Gmail, juggles multiple accounts under a single OAuth client, refreshes tokens over time, and authorizes accounts on a headless server. If you just want to get running, jump to Quickstart.

The OAuth model

gmail-mcp authenticates using a Google "Desktop app" OAuth client (an *installed application* in OAuth 2.0 terms), driven by the InstalledAppFlow helper from google-auth-oauthlib.

Why an installed-app / desktop client. Installed apps run on a machine the end user controls, so OAuth treats them as public clients: the client_secret in the downloaded client_secret.json is *not* assumed to be confidential. That's the right trust model for a local CLI/desktop tool — there's no server-side component that could keep a secret truly secret, and security rests on the user controlling the redirect (the loopback address) rather than on secret confidentiality. It's the client type Google recommends for command-line and desktop tools.

The loopback redirect flow. After you approve consent in a browser, Google redirects the authorization code to http://localhost: /, where a tiny throwaway HTTP server (started by InstalledAppFlow.run_local_server) catches it. gmail-mcp pins this to a fixed port (default 8765, override with GMAIL_MCP_OAUTH_PORT) and runs with open_browser=False so it works on machines with no browser — see The headless auth path.

Scopes requested. Four granular scopes — never the full-mailbox https://mail.google.com/:

gmail.send is not requested. Without it the credential simply has no Gmail API path to send mail — the drafts-only behavior is a property of the grant, not just an omitted tool. gmail.settings.sharing is likewise not requested, so no filter can forward mail to another address. The scope list lives in one place: SCOPES in src/gmail_mcp/config.py.

Adding the filter scope to an existing install: widening SCOPES does not

retro-grant already-authorized accounts. Each account must re-run

gmail-mcp-auth add to re-consent to the new scope; until it does, the filter

tools return a 403 insufficient scope error.

The multi-account model

• One OAuth client authorizes many accounts. You create a single Google Cloud project and one "Desktop app" OAuth client, then run the consent flow once per Gmail account, signing into the account you want to add each time. A single client_secret.json can authorize any number of accounts.
• Each account is a row in SQLite. Every authorized account is stored in the accounts table (~/.gmail-mcp/tokens.db, override with GMAIL_MCP_DB), keyed by email. The row holds the long-lived refresh token, the most recent access-token blob, the granted scopes, and timestamps.
• **