gmail-mcp

Gmail second account MCP server

Read and write one Gmail mailbox from Claude.ai and Claude Code. Claude.ai's own Gmail connector handles a single account, so this exists for the second one: run an instance per mailbox and each connector reaches exactly the address it was given.

One mailbox per instance

Which account an instance serves comes from GMAIL_CREDENTIALS_DIR, and nothing else is reachable from that process. That separation is the point rather than a limitation: a draft cannot land in the wrong mailbox when the server only ever holds one set of credentials.

Related MCP server: Gmail MCP Local Server

Tools

Reading

Writing

The two send tools are marked destructive and say so in their descriptions: they reach other people and cannot be undone. The safe shape is gmail_create_draft, read it, then gmail_send_draft once a person has approved the text.

Searching

gmail_search takes the same operators as the Gmail search box:

is:unread from:client.com
subject:invoice has:attachment newer_than:7d
label:important -in:trash

It returns headers and a snippet per message rather than bodies, so a wide search stays small. Follow up with gmail_get_message or gmail_get_thread.

How it fits together

Claude.ai / Claude Code
        |  HTTPS
   Cloudflare Tunnel, or any proxy that gives you HTTPS
        |
   nginx  127.0.0.1:8461
        |
   auth-server.js  :8462    handles the login and the tokens
        |
   gmail-mcp  :8460         the server itself, local only
        |
   gmail.googleapis.com

The MCP has no login of its own and refuses to listen on anything but the local machine, so everything reaching it has already passed the login.

Setup

You need a Google Cloud OAuth client with the Gmail API enabled, and a refresh token for the mailbox. The credentials directory holds two files:

credentials.json        {"refresh_token": "..."}
gcp-oauth.keys.json     the downloaded OAuth client

gmail.modify is the scope to grant. It covers reading, labelling, drafting and sending; drop to gmail.readonly plus gmail.compose if you would rather the credentials themselves could not send.

git clone https://github.com/rollecode/gmail-second-account-mcp.git
cd gmail-second-account-mcp
uv venv && uv pip install -e .
npm install --omit=dev

CONFIG_DIR=~/.config/gmail-mcp node set-password.js 'your-password-here'
openssl rand -hex 32 > ~/.config/gmail-mcp/token
chmod 600 ~/.config/gmail-mcp/token

Fill in YOUR_USER, the hostname and the credentials directory in systemd/*.service and nginx/gmail-mcp.conf, then:

sudo cp systemd/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now gmail-mcp gmail-mcp-auth

sudo cp nginx/gmail-mcp.conf /etc/nginx/sites-enabled/gmail-mcp
sudo nginx -t && sudo systemctl reload nginx

Point a tunnel or an HTTPS proxy at 127.0.0.1:8461. OAuth needs HTTPS.

Check from outside: discovery returns metadata, and /mcp without a token must return 401.

curl https://your-host/.well-known/oauth-authorization-server
curl -o /dev/null -w '%{http_code}\n' -X POST https://your-host/mcp

Connecting

Claude.ai: Settings, Connectors, Add custom connector, https://your-host/mcp, client ID and secret blank.

Claude Code:

claude mcp add --transport http gmail https://your-host/mcp \
  --header "Authorization: Bearer $(cat ~/.config/gmail-mcp/token)" --scope user

Locally over stdio, with no server at all:

GMAIL_CREDENTIALS_DIR=/path/to/creds claude mcp add gmail -- /path/to/.venv/bin/gmail-mcp

Settings

Access tokens are refreshed in memory as they expire; only the refresh token is read from disk.

Credits

The login layer comes from rollecode/obsidian-remote-mcp.