Google Mail MCP

google-mail-mcp

Gmail as MCP tools. Read your mail without letting it read your assistant.

A single Go binary that speaks MCP over stdio. It runs as a subprocess of your client, on your own machine, against your own Google account. There is no server to host and no service account: you create a Google OAuth client, log in once, and the refresh token stays in your OS keyring.

It is for one person who uses Gmail, on a Workspace or a personal Google account, and wants an assistant to search, read, organize and draft mail as them. It works inside a mailbox: a calendar invitation's event, a linked Drive file and a Chat space belong to servers built on those APIs.

Goals and non-goals

Goals:

• Mail never steers the assistant through the server. It comes back marked as data, hidden text is removed and counted, nothing it links to is fetched, and the writes that redirect mail do not exist.
• Nothing reaches another person, or is lost for good, unless you turn it on. Sending, permanent deletion and settings changes are not registered by default, and removal is trash.
• A write changes only what it names. Writes take explicit ids, never a search, report each item on its own, and take dry_run.
• Reads are bounded. Every read has a budget and says what it left out and how to continue.
• Act as you, and log nothing about your mail. Every call runs as the signed-in account, and the logs never carry content or addresses.

Non-goals:

• Push notifications. Gmail's watch delivers to a Cloud Pub/Sub topic, which a stdio process cannot own. list_changes polls instead.
• Bulk operations over a search. No "archive everything from X" and no relabeling by query; a search is a read you have seen first.
• Settings that send mail elsewhere. Auto-forwarding, forwarding addresses, filters that forward, delegation and send-as identities are never written.
• Mailbox migration. Importing or inserting mail that was never sent is out.
• Rendering HTML. HTML becomes text, and nothing is fetched.
• A contacts directory. Addresses come from you or from the message being answered; turning a name into an address belongs to a People API server.
• Workspace administration. No service accounts and no domain-wide delegation.
• A hosted service. It speaks stdio only, so Claude on the web and on mobile cannot reach it.
• Asking you before a call. Your client approves each call; the server asks nothing.

What makes this one different

Every message was written by somebody other than you, and some of it is written to steer an AI assistant. So mail comes back inside blocks marked with a per-call boundary token; text a reader of the mail would not have seen — hidden styles, zero-width characters, text colored like its background — is removed and counted; nothing a message links to or embeds is fetched; and a link whose text names a different site from its target is flagged.

The writes that would make a persuaded assistant dangerous are not there. Automatic forwarding, filters that forward and delegation are not implemented; forwarding one message attaches it to a draft. Sending is not registered unless you turn it on, and then only a draft can be sent. Removal is trash; permanent deletion is not registered unless you turn it on, and is the only thing that asks Google for full mail access.

Reads are bounded. A thread comes back newest first within a character budget, with quoted replies and signatures collapsed to a line saying how much was hidden, and every omission says how to continue. Non-ASCII subjects, names and filenames decode in any charset.

The design and the decisions behind it are in docs/architecture.md.

Install

go install github.com/mmedum/google-mail-mcp/v4/cmd/google-mail-mcp@latest

Or take an archive from the latest release — Linux, macOS and Windows, on amd64 and arm64 — and verify it before you run it:

sha256sum -c checksums.txt --ignore-missing

The checksum file is signed with a keyless Sigstore certificate tied to

the release workflow's identity.

cosign verify-blob checksums.txt \ --bundle checksums.txt.bundle \ --certificate-identity-regexp 'https://github\.com/mmedum/google-mail-mcp/' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com

And the archive itself carries build provenance.

gh attestation verify google-mail-mcp_*.tar.gz --repo mmedum/google-mail-mcp

Every archive ships an SBOM. Builds are reproducible: rebuilding a tag gives the same bytes.

Claude Desktop

Every release also carries a .mcpb bundle. Open it and Claude Desktop installs the server and asks for the settings a client's configuration would carry: your OAuth client JSON, the profile, read-only, the switches and the attachment folder. Sending (enable_send), permanent deletion (enable_destructive) and settings changes (enable_settings) stay off unless you turn them on, and read-only cannot be combined with any of them. Signing new drafts (draft_signature) is off too, and registers no tool. This server asks nobody before a call. Claude Desktop approves each tool, with Allow once or Always allow, and a tool you always allow then runs unasked, so leave a switch off unless you need its tools.

The bundle covers macOS, Windows and Linux on both architectures. Its SHA-256 is in the same signed checksums.txt.

The bundle does not log you in. Install the binary as well, run google-mail-mcp login --client-secret once, and the bundle uses the same credentials.

Set up Google

docs/gcp-setup.md has the whole of it: a Cloud project with the Gmail API enabled, a consent screen (with the scopes for how you will run the server, on an External app), and a Desktop app OAuth client. Then:

google-mail-mcp login --client-secret ~/path/to/client_secret.json

google-mail-mcp doctor

Every Gmail scope that reads mail is one Google calls restricted. For your own use that costs nothing, but an External client in Testing gets refresh tokens that expire after seven days; docs/troubleshooting.md says what that looks like.

Logging in over SSH

The callback goes to the *remote* host's loopback address while your browser is local, so forward the port. Run google-mail-mcp login --no-browser: it prints the authorization URL and the exact ssh -L line for the port it picked. Run that line in a second local terminal, then open the URL locally.

Connect a client

Claude Code:

claude mcp add google-mail -- google-mail-mcp

Or, in a client config file:

{

"mcpServers": { "google-mail": { "command": "google-mail-mcp" } } }

Every setting is a GMAIL_* environment variable, listed in docs/configuration.md. The ones worth knowing first: GMAIL_READ_ONLY=true registers only the read tools and asks for read-only access; GMAIL_LOCAL_DIR is the one directory attachments may be saved to; GMAIL_PROFILE lets one machine hold several accounts.

Tools

Searches take Gmail's own search language in q, plus after and before as real instants — Gmail reads a date written inside q as midnight Pacific time. Every result states the quota it spent. Every write takes dry_run, names what it touches by id, and says what it changed, read from Gmail's answer. GMAIL_READ_ONLY=true leaves the writes out. A tool marked "only with" a setting is not registered at all unless that setting is on.

For clients that attach rather than call, gmail://threads/{id}, gmail://messages/{id} and gmail://labels carry the same text as get_thread, get_message and list_labels.

Safety

• Mail is data. It arrives marked, with what was hidden removed and counted, and no tool description tells a model to act on it.
• Nothing reaches another person by default. Drafts wait in Gmail to be sent, and by default no tool changes a setting. Forwarding settings are shown, never set.
• Settings are opt-in. With GMAIL_ENABLE_SETTINGS=true the server can set a signature and create filters. A filter cannot forward. A filter that trashes mail is its own tool, create_trash_filter, and it and delete_filter also need GMAIL_ENABLE_DESTRUCTIVE=true and `confirm: tr