The refresh-token lifetime is set by the OAuth consent screen, not by this project: Internal on a Workspace account never expires, External in Testing mode expires after 7 days. Recovery is deleting `token.json` and re-running the auth command. Most of the defences ship off and are switched on in the config file — the exception is the attachment denylist, which is active by default and refuses to attach `~/.ssh/`, `~/.aws/`, `id_rsa`, `.env` or `token.json`.
A comprehensive Gmail server — send, reply, forward, drafts, search, read, attachments, trash, labels, filters, signature and vacation responder — built with the assumption that the thing calling it might be compromised.
- Send and reply: `send_email`, `reply_to_message`, `forward_message`, plus `preview_send_email` and `confirm_send_email` for a two-step flow
- Drafts: `create_draft`, `list_drafts`, `update_draft`, `send_draft`, `delete_draft`
- Read: `get_profile`, `get_message`, `search_threads`, `get_thread`, with `get_message_attachments` and `download_attachment`
- Organise: labels (`create_label`, `label_message`, `label_thread` and their inverses), filters (`list_filters`, `create_filter`, `delete_filter`), and trash and untrash for both messages and threads
- Settings: `get_signature` / `update_signature` and `get_vacation_responder` / `set_vacation_responder`
- A tamper-evident audit log, on by default: every write, send, modify and download appends a JSON line chained by SHA-256, with rotation, startup verification and an `mcp-gmail-manager-verify-log` CLI
The PyPI package mcp-gmail-manager, version 0.3.5, installed with pipx and registered as `claude mcp add gmail-manager -- mcp-gmail-manager`. Python 3.10 or higher. You supply a Google Cloud project with the Gmail API enabled and a Desktop-type OAuth client; save the downloaded JSON as `credentials.json` in the config directory and run `mcp-gmail-manager-auth`, which binds `localhost:8765` and prints an authorisation URL — on a headless host, forward that port over SSH first. Scopes requested are `gmail.modify` and `gmail.settings.basic` only. `GMAIL_MCP_CONFIG_DIR`, `GMAIL_MCP_CREDENTIALS` and `GMAIL_MCP_TOKEN` override the paths.
One command plus a key — pipx install mcp-gmail-manager, then supply credentials