gmail-mcp

MCP server for Gmail with full read/write coverage: search, send, reply, drafts, labels, filters, vacation responder, auto-forwarding, signature, and attachment handling (download + render to PDF).

Built because the commonly available Gmail MCP integrations are read/label-only (no sending, no attachment export, no settings management). This one closes that gap using the standard Gmail API with your own OAuth client.

Why it's safe by design

The OAuth scope used is gmail.modify, not the full https://mail.google.com/ scope. This means the Gmail API itself rejects permanent delete (messages.delete, batchDelete, threads.delete) — the only "removal" tool is trash/untrash, which is reversible.

Related MCP server: mcp-gsuite

Tools (34)

Read / search

Send / reply (require confirmed=True)

Drafts

Labels

Organization (trash only, reversible)

Settings

Confirmation pattern

Tools that send mail, delete something, or change externally-visible settings take confirmed: bool = False. Called without it, they return {"requires_confirmation": true, ...} with a preview of what would happen — the calling agent must show that preview to the user and only repeat the call with confirmed=True after explicit approval. confirmed=True is a technical flag, not a substitute for actually asking.

Setup

1. Create a Google Cloud project (or reuse one) and enable the Gmail API.

2. Create an OAuth 2.0 Client ID of type "Desktop app" and download it as client_secret.json.

3. On the OAuth consent screen, add these scopes: gmail.modify, gmail.settings.basic, gmail.settings.sharing.

4. If the app is in "Testing" mode, add your own Google account as a test user.

5. Install dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   # weasyprint also needs a system package for PDF rendering:
   #   macOS: brew install pango
   #   Debian/Ubuntu: apt install libpango-1.0-0 libpangocairo-1.0-0

6. Run the OAuth flow once per account:

   CLIENT_SECRET_PATH=~/.config/gmail-mcp/client_secret.json \
   TOKEN_OUT=~/.config/gmail-mcp/token.json \
     python3 setup_auth.py

   This opens a browser — log in and grant access. Run it again with a different TOKEN_OUT for each additional Gmail account you want to expose as a separate MCP server instance.

MCP client configuration

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["/path/to/gmail-mcp/server.py"],
      "env": {
        "GMAIL_TOKEN_PATH": "~/.config/gmail-mcp/token.json"
      }
    }
  }
}

To expose a second account, add another entry (e.g. gmail-work) pointing at the same server.py with a different GMAIL_TOKEN_PATH.

Notes on usage (for the calling agent)

• API quota: 6,000 units/user/minute. messages.get costs 20 units, messages.list costs 5. Filter with Gmail's query syntax instead of fetching everything and filtering client-side.

• Use get_thread instead of N get_message calls when you need a whole conversation.

• attachment_id is not stable across calls — always use the one from the same response you're about to call download_attachment with.

• Prefer body_html over body_text for anything with lists, bold text or links — Gmail does not reflow plain text, so \n becomes a hard line break.

• No automatic retry on 429 — back off manually if you hit a rate limit.

License

MIT — see LICENSE.