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")

  ── [email protected] ───────────────────────────────
  from: [email protected]    subject: Invoice #4821    (id 18f...)

  ── [email protected] ─────────────────────────────────
  from: [email protected]        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