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.

Tools (34)

Read / search

Tool	What it does
get_profile	Account email and message/thread totals
list_messages	Search with Gmail query syntax (query, label_ids, pagination)
get_message	Parsed message: from/to/cc/subject/date/body/labels/attachments
get_thread	Full thread with all messages parsed
list_attachments	Real attachment metadata for a message (with attachment_id)
download_attachment	Download an attachment to disk
export_message_to_pdf	Render a message (HTML + inline images resolved) to PDF via WeasyPrint
export_thread_to_pdf	Same, for a full thread (one message per page)

Send / reply (require confirmed=True)

Tool	What it does
send_message	Send a new email (text/HTML, attachments)
reply_message	Reply within a thread, auto-generating In-Reply-To/References

Drafts

Tool	What it does
list_drafts / get_draft	List and read drafts
create_draft / update_draft / delete_draft	Manage drafts
send_draft	Send an existing draft (confirmed=True)

Labels

Tool	What it does
list_labels / create_label / update_label	Label management
delete_label	Delete a label (confirmed=True)
modify_message_labels / modify_thread_labels	Add/remove labels on a message or full thread

Organization (trash only, reversible)

Tool	What it does
trash_message / untrash_message	Move to trash / restore
batch_modify_messages	Change labels on several messages at once

Settings

Tool	What it does
get_vacation / update_vacation	Vacation auto-responder
get_auto_forwarding / update_auto_forwarding	Auto-forwarding (confirmed=True when enabling — this is a data-exfiltration vector, double check the destination address)
list_filters / create_filter / delete_filter	Filters (delete_filter requires confirmed=True)
list_send_as / update_signature	Send-as aliases and HTML signature (confirmed=True)

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.

Env var	Default	Purpose
GMAIL_TOKEN_PATH	~/.config/gmail-mcp/token.json	Path to the OAuth token for this account

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.