gmail-mcp

An MCP 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.

| Tool | Arguments |

... View full README on GitHub