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: Gmail MCP Server

Tools (41)

Read / search

Send / reply (require confirmed=True)

Drafts

Labels

Organization (trash only, reversible)

Incremental sync

Mailbox delegation

⚠️ Requires domain-wide delegation. Verified live: on a regular Gmail/Workspace account without that admin-level setup, these 3 tools return 403: Access restricted to service accounts that have been delegated domain-wide authority. Left implemented for accounts where it does apply.

Authorized forwarding addresses

Different from get_auto_forwarding/update_auto_forwarding below (which toggle forwarding to an already-authorized address): these manage which addresses are allowed as a target in the first place.

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.

Security

• Every tool ships with MCP Tool Annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so MCP clients can use them to decide whether to prompt for confirmation before running a tool.

• Execution errors propagate as real MCP protocol errors (isError: true), not as a JSON payload that looks like a success with an "error" key buried inside — so the calling model actually sees the failure and can self-correct instead of silently treating it as a success.

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.