gmail-mcp — multi-account Gmail MCP server

One local MCP server that serves several Gmail accounts, each under a short alias (alice-work, bob-work, ...). Every tool takes an account parameter, and the GMAIL_ACCOUNTS env var restricts a server instance to a subset of accounts — so each Cowork workstream sees only its own two inboxes.

Capabilities: search/read threads, manage labels, create drafts. Deliberately absent: sending. There is no send tool, so no agent connected to this server can send mail — a human reviews drafts and sends from Gmail. (Note: the underlying OAuth scope gmail.modify would technically allow sending; the restriction is enforced by this server's tool surface, not by Google. Don't point other software at the stored tokens.)

1. Google Cloud setup (once, ~5 minutes)

1. Go to https://console.cloud.google.com/ and create a project (any name, e.g. gmail-mcp).
2. APIs & Services → Library → search "Gmail API" → Enable.
3. APIs & Services → OAuth consent screen:
   • User type: External, fill in the app name + your email.
   • Under Audience / Test users, add all four Gmail addresses. (In Testing mode only listed test users can authorize — that's fine, and you skip Google's app verification entirely.)
4. APIs & Services → Credentials → Create credentials → OAuth client ID:
   • Application type: Desktop app.
   • Download the JSON and save it as ~/.gmail-mcp/credentials.json.

Heads-up: in Testing mode Google expires refresh tokens after 7 days unless the consent screen is published. After everything works, go back to the consent screen and click Publish app (you can ignore the verification warning for personal use) so tokens stop expiring weekly.

2. Authorize each account (once per account)

uv run gmail-mcp auth alice-work      # browser opens; sign in as that account
uv run gmail-mcp auth alice-personal
uv run gmail-mcp auth bob-work      # the other person signs in here
uv run gmail-mcp auth bob-personal
uv run gmail-mcp accounts              # verify: alias -> email [ok]

Sign in with the matching Google account each time — the alias is whatever you type, so double-check the account picker. Tokens land in ~/.gmail-mcp/tokens/, readable only by your macOS user.

3. Wire into Claude — one server entry per workstream

Register the same server twice with different GMAIL_ACCOUNTS, then enable the matching one in each workstream/session.

Claude Desktop / Cowork (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gmail-stream-a": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/gmail-mcp", "gmail-mcp", "serve"],
      "env": { "GMAIL_ACCOUNTS": "alice-work,bob-work" }
    },
    "gmail-stream-b": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/gmail-mcp", "gmail-mcp", "serve"],
      "env": { "GMAIL_ACCOUNTS": "alice-personal,bob-personal" }
    }
  }
}

Claude Code, per workstream folder (or with claude mcp add), in .mcp.json:

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/gmail-mcp", "gmail-mcp", "serve"],
      "env": { "GMAIL_ACCOUNTS": "alice-work,bob-work" }
    }
  }
}

If uv isn't on the app's PATH, use its absolute path (which uv).

Tools

Tool	What it does
list_accounts	Aliases + emails this instance serves
search_threads	Gmail query syntax (from:, newer_than:7d, ...)
get_thread	Full thread with decoded message bodies
list_labels / create_label	Labels, incl. nested Clients/Acme
modify_thread_labels	Add/remove by name or ID; archive = remove INBOX
create_draft	New draft or threaded reply (reply_to_thread_id)
list_drafts	Existing drafts

Layout

• ~/.gmail-mcp/credentials.json — OAuth client secret (shared by all accounts)
• ~/.gmail-mcp/accounts.json — alias → email registry
• ~/.gmail-mcp/tokens/<alias>.json — per-account tokens
• GMAIL_MCP_HOME overrides the config dir; GMAIL_ACCOUNTS restricts visible accounts