How do I install Google Mail?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Google Mail need an API key?

No required environment variable is listed on this record.

What transport does Google Mail use?

Google Mail runs locally over stdio.

When was Google Mail last checked?

Last checked 2026-11-09. Gmail over MCP from your own account: search, read threads and messages, labels and drafts.

Google Mail MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

mcpb https://github.com/mmedum/google-mail-mcp/releases/download/v4.0.2/google-mail-mcp_4.0.2.mcpb

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add io.github.mmedum-google-mail-mcp -- mcpb https://github.com/mmedum/google-mail-mcp/releases/download/v4.0.2/google-mail-mcp_4.0.2.mcpb

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.mmedum-google-mail-mcp": {4      "command": "mcpb",5      "args": [6        "https://github.com/mmedum/google-mail-mcp/releases/download/v4.0.2/google-mail-mcp_4.0.2.mcpb"7      ]8    }9  }10}

claude_desktop_config.json

Local · mcpbPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 4.0.2
Last checked

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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. 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.

Install

go install github.com/mmedum/google-mail-mcp/v3/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 three 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. 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 <your client JSON> 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

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/runbook.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 now: 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

Tool	What it does
`get_profile`	The signed-in account, its totals and the current history id
`search_threads`	Find conversations with a Gmail search
`search_messages`	Find single messages with a Gmail search
`get_thread`	Read a conversation, newest first, within a budget
`get_message`	Read one message, by id or by its `Message-ID` header
`read_attachment`	Read an attachment's text: plain text, CSV, Markdown, JSON, HTML, a calendar or an attached email
`list_labels`	Every label, optionally with counts
`list_drafts`	Unsent drafts
`get_draft`	Read one draft
`list_changes`	What changed since a history id, and when that cursor has expired
`get_settings`	Forwarding, vacation reply, send-as addresses, IMAP and POP, read-only
`list_filters`	The account's filters, with any that forward mail flagged
`download_attachment`	Save an attachment into `GMAIL_LOCAL_DIR`, never overwriting; only when that is set
`download_attachments`	Save several attachments of one message, or all of them, the same way; only when `GMAIL_LOCAL_DIR` is set
`create_draft`	Save a new draft, a reply threaded by the server and quoting its parent if asked, or a forward with the original attached; nothing is sent
`update_draft`	Change only the fields given, refusing a draft that changed since it was read
`delete_draft`	Delete a draft for good, named with the message it holds, with `confirm: true`
`modify_labels`	Add and remove labels on up to 100 messages or threads, reported per item

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. The last eight tools are not registered at all unless their settings are 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: true. The vacation reply answers other people, so it also needs GMAIL_ENABLE_SEND=true, it only ever answers contacts or the account's domain, and turning it on needs confirm: true.
Sending is opt-in and goes through a draft. With GMAIL_ENABLE_SEND=true, send_draft sends a draft exactly as it is stored. Every recipient, the thread's own participants included, must be written out in confirm_recipients, the call carries the draft's subject and first line, so your client's prompt shows what goes, and a send Gmail does not confirm is never repeated.
Removal is trash. Gmail keeps trashed mail for 30 days, and restore brings it back. By default the only permanent removal is delete_draft, which needs the message the draft holds and confirm: true. delete_permanently and delete_label exist only with GMAIL_ENABLE_DESTRUCTIVE=true, which also asks for the one scope that can delete; each call needs confirm: true.
Your client approves each call. The server does not ask you itself. claude.ai and Codex prompt for the tools marked destructive: every write that sends, changes a setting or cannot be undone. VS Code prompts for every tool that writes. In Claude Code, delete_permanently and delete_label ask on every call whatever your rules say, since mail deleted for good skips the trash and a label comes off every message. For the rest, list the calls you want to approve one by one under permissions.ask in your settings, with the name you gave the server in place of google-mail. For example, the writes that send, change a setting or delete:
```
{
  "permissions": {
    "ask": [
      "mcp__google-mail__send_draft", "mcp__google-mail__set_vacation",
      "mcp__google-mail__update_signature", "mcp__google-mail__create_filter",
      "mcp__google-mail__create_trash_filter", "mcp__google-mail__delete_filter",
      "mcp__google-mail__delete_draft", "mcp__google-mail__delete_permanently",
      "mcp__google-mail__delete_label"
    ]
  }
}
```

docs/security.md has the whole of it.

Getting help

Run google-mail-mcp doctor first: it checks the client JSON, the token, the granted scopes and whether the Gmail API is enabled, and names what is missing. docs/runbook.md covers the common surprises. Then open an issue with doctor's output and the version. Do not paste a tool result: it is mail, and carries other people's words and addresses.

Versioning

Semantic versioning. The tool names and their output fields are the public contract; CHANGELOG.md marks anything you have to act on as Breaking.

Development

make check

That is what CI runs. docs/development.md says what each gate holds and how the live driver works.

Documentation

docs/README.md is the index. The design, the platform facts behind it and a verdict on every Gmail API method are in docs/architecture.md.

Contributing

See CONTRIBUTING.md.

Security

Report a vulnerability through a private advisory; see SECURITY.md.

Code of conduct

CODE_OF_CONDUCT.md.

License

Apache 2.0.