# google-mail-mcp

[![CI](https://github.com/mmedum/google-mail-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mmedum/google-mail-mcp/actions/workflows/ci.yml)
[![Latest release](https://img.shields.io/github/v/release/mmedum/google-mail-mcp?sort=semver)](https://github.com/mmedum/google-mail-mcp/releases/latest)
[![Go Reference](https://pkg.go.dev/badge/github.com/mmedum/google-mail-mcp.svg)](https://pkg.go.dev/github.com/mmedum/google-mail-mcp)
[![License: Apache 2.0](https://img.shields.io/github/license/mmedum/google-mail-mcp)](./LICENSE)

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`](docs/architecture.md).

## Install

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

Or take an archive from the
[latest release](https://github.com/mmedum/google-mail-mcp/releases/latest)
— Linux, macOS and Windows, on amd64 and arm64 — and verify it before you
run it:

```bash
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 <your client JSON>` once, and the
bundle uses the same credentials.

## Set up Google

[`docs/gcp-setup.md`](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:

```bash
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`](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:

```bash
claude mcp add google-mail -- google-mail-mcp
```

Or, in a client config file:

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

Every setting is a `GMAIL_*` environment variable, listed in
[`docs/configuration.md`](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

| 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 |
| `trash` | Move up to 100 messages or threads to the trash, kept 30 days |
| `restore` | Take messages or threads out of the trash |
| `create_label` | Create a user label |
| `update_label` | Rename a user label or change how it shows |
| `send_draft` | Send a draft, naming every recipient, its subject and its first line; only with `GMAIL_ENABLE_SEND=true` |
| `delete_permanently` | Delete up to 100 messages or threads for good, with `confirm: true`; only with `GMAIL_ENABLE_DESTRUCTIVE=true` |
| `delete_label` | Delete a user label, with `confirm: true`; only with `GMAIL_ENABLE_DESTRUCTIVE=true` |
| `update_signature` | Set the signature of one of the account's addresses; only with `GMAIL_ENABLE_SETTINGS=true` |
| `create_filter` | Create a filter for mail that arrives from now on; it cannot forward or trash; only with `GMAIL_ENABLE_SETTINGS=true` |
| `create_trash_filter` | Create a filter that moves matching mail to the trash as it arrives, with `confirm: true`; only with `GMAIL_ENABLE_SETTINGS=true` and `GMAIL_ENABLE_DESTRUCTIVE=true` |
| `delete_filter` | Delete a filter, naming its criteria, with `confirm: true`; only with `GMAIL_ENABLE_SETTINGS=true` and `GMAIL_ENABLE_DESTRUCTIVE=true` |
| `set_vacation` | Turn the vacation reply on for contacts or the domain, or off; only with `GMAIL_ENABLE_SETTINGS=true` and `GMAIL_ENABLE_SEND=true` |

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: 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 tool that changes the mailbox but `create_draft` and
  `create_label`, which only add. 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`. The example
  allows the server's tools and asks for every call that sends, changes
  a setting or deletes for good. An ask rule wins over an allow rule.
  The everyday writes to drafts, labels and the trash run unasked:

  ```json
  {
    "permissions": {
      "allow": ["mcp__google-mail__*"],
      "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"
      ]
    }
  }
  ```

  A client that runs with nobody watching can make every write that is
  registered, so leave `GMAIL_ENABLE_SEND`, `GMAIL_ENABLE_DESTRUCTIVE`
  and `GMAIL_ENABLE_SETTINGS` off for one.
- **Files go to one directory.** `download_attachment` and
  `download_attachments` write only into `GMAIL_LOCAL_DIR`, under a name
  made safe, and never over an existing file.
- **Logs never carry mail.** No address, subject, body, label name or
  query; ids are cut to six characters. A test drives every tool with
  marker values and fails if one reaches a log, which is what makes a debug
  log safe to paste.
- Everything above but the client's prompt is enforced in the server.
  Tool annotations are set, but they are hints a client may ignore.

[`docs/security.md`](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/troubleshooting.md`](docs/troubleshooting.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`](CHANGELOG.md) marks anything you have
to act on as **Breaking**.

## Development

`make check` runs everything CI runs. `make live` drives the built binary
against a real account, and `make evals` scores a model against the
tools; both are run by hand. [`CONTRIBUTING.md`](CONTRIBUTING.md) covers
the gates, the live run and the review flow.

## Documentation

- [`docs/architecture.md`](docs/architecture.md): the request flow, the
  package layout, and the design decisions a contributor should not
  undo.
- [`docs/configuration.md`](docs/configuration.md): every setting, where
  state is stored, and `status --json`.
- [`docs/gcp-setup.md`](docs/gcp-setup.md): the Google Cloud project,
  consent screen and OAuth client, step by step.
- [`docs/troubleshooting.md`](docs/troubleshooting.md): symptoms and
  their fixes, then rotating the token, revoking access and handling a
  suspected exposure.
- [`docs/security.md`](docs/security.md): the threat model.
- [`docs/release.md`](docs/release.md): how a release is cut and
  checked.

## Contributing

See [`CONTRIBUTING.md`](CONTRIBUTING.md).

## Security

Report a vulnerability through a private advisory; see
[`SECURITY.md`](SECURITY.md).

## Code of conduct

[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).

## License

[Apache 2.0](LICENSE).