Google Mail MCP server

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 works inside a mailbox. A calendar invitation's event, a linked Drive file and a Chat space belong to servers built on those APIs.

Why google-mail-mcp

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. Forwarding, filters that forward and delegation are not implemented. 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.

Install

go install github.com/mmedum/google-mail-mcp/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 your OAuth client JSON. It 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, the scopes for how you will run the server, and a Desktop app OAuth client. Then:

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

Shortened. The full README is on GitHub.