Skip to main content
Glama
gmail-accounts

gmail-accounts

by sviatil0

gmail-mcp

A multi-account Gmail MCP server for AI agents (Claude Code and anything else that speaks MCP), with one design goal above all: the agent can read and draft freely, but a human must approve every send.

Built because the hosted Gmail connectors bind one account at a time and send without friction. This server binds any number of Gmail accounts behind short aliases (work, school, ...) and splits capabilities by risk:

Capability

Who can do it

Search, read threads, list drafts

Agent, freely

Create and update drafts

Agent, freely

Send

Only with a single-use approval token a human mints in a terminal

The server is registered as gmail-accounts (not gmail) on purpose: if you also run a hosted Gmail connector, near-identical tool names make an agent read the wrong mailbox and report a confident false negative.

How the send gate works

  1. The agent stages a draft and asks you to approve it.

  2. You run gmail-approve in your own terminal, review the exact RFC822 payload, and get a one-time token bound to that draft's content hash.

  3. The agent calls the send tool with the token. Wrong draft, edited draft, reused token, expired token: all refused.

The send tool also carries anthropic/requiresUserInteraction, so Claude Code prompts a human even in bypassPermissions mode. The token CLI is a mistake interlock; the harness prompt is the enforced boundary.

Related MCP server: multi-email

Setup

Requires Python 3.12+ and uv.

1. Google Cloud OAuth client

Create a project at console.cloud.google.com, enable the Gmail API, create an OAuth client ID of type Desktop app, and download the JSON to:

~/.config/gmail-mcp/client_secret.json

2. Declare your accounts

~/.config/gmail-mcp/accounts.json:

{
  "accounts": [
    { "alias": "personal", "email": "alice.personal@gmail.com" },
    { "alias": "work",     "email": "alice.work@gmail.com" }
  ]
}

Adding an account later is a config edit plus one auth run; the file is re-read on every call, so no restart is needed.

3. Authorize each account

uv sync
scripts/auth-all.sh          # runs the OAuth flow once per alias, skips done ones

Each grant is verified against its alias: authorizing the wrong Google account in the browser is detected and refused, not silently stored.

4. Register with Claude Code

claude mcp add gmail-accounts -- uv run --directory /path/to/gmail-mcp --frozen --no-sync gmail-mcp

Everyday use

Every tool takes an account alias. Ask the agent things like "search work for the invoice thread" or "draft a reply on personal". When it is time to send:

gmail-approve            # lists pending sends, shows the payload, mints a token

Health check:

uv run gmail-mcp-health

Security notes

  • Secrets never enter the repo: client_secret.json and per-account tokens live in ~/.config/gmail-mcp/ (override with GMAIL_MCP_CONFIG).

  • All config writes are atomic (tmp + fsync + rename); a crash mid-write never leaves a torn file.

  • stdout is the JSON-RPC channel; nothing in the package may print() (enforced by ruff T201), so diagnostics cannot corrupt the protocol.

Tests

uv run pytest

Available Tools

12 tools
create_draftC

(unconfigured) Create a draft. Pass reply_to_message_id to keep it in-thread.

Inputs: to (required), body (required), account (required), subject (required), +2 more.

get_attachmentC
Read-only

(unconfigured) Download one attachment to a path.

Inputs: account (required), save_path (required), message_id (required), attachment_id (required), +1 more.

get_messageC
Read-only

(unconfigured) One message with bodies and attachment stubs.

Inputs: account (required), message_id (required).

get_threadB
Read-only

(unconfigured) Thread metadata and snippets; bodies via get_message.

Inputs: account (required), thread_id (required), max_messages.

label_threadC

(unconfigured) Add or remove labels on a thread.

Inputs: account (required), thread_id (required), add, remove.

list_accountsA
Read-only

(unconfigured) List configured accounts and local token state. Call this first.

Inputs: no named parameters.

list_draftsC
Read-only

(unconfigured) List drafts.

Inputs: account (required).

list_labelsC
Read-only

(unconfigured) List labels.

Inputs: account (required).

sendA
Destructive

(unconfigured) Send a draft that a human already approved via the gmail-approve CLI.

Inputs: account (required), approval_id (required).

stage_sendA

(unconfigured) Freeze a draft and request human approval to send. Does NOT send.

Inputs: account (required), draft_id (required), allow_attachments.

update_draftC

(unconfigured) Replace a draft's content. Invalidates any staged approval.

Inputs: to (required), body (required), account (required), subject (required), +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct operation: search, thread/message retrieval, attachment download, threading labels, and a clearly separated draft/stage/send pipeline. Even adjacent tools like get_thread and get_message are delineated by thread-level vs message-level detail.

    Naming Consistency4/5

    Tool names mostly follow a predictable verb_noun snake_case pattern with list_*, get_*, and create_/update_ prefixes. The bare verbs search and send, plus stage_send, are minor deviations but still readable and consistent in style.

    Tool Count5/5

    Twelve tools is well-scoped for a Gmail account server covering search, reading, attachments, labels, drafts, and sending. Each tool earns its place with no obvious redundancy.

    Completeness4/5

    Core email workflows are covered: search, read, download attachments, label threads, create/update drafts, and send through an approval flow. Minor gaps like creating labels, adding attachments to drafts, or managing read state are plausible but not critical to the server's apparent purpose.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Connects AI assistants to multiple Gmail accounts simultaneously, enabling search, read, draft, send, and reply operations with per-account permission controls.
      54
      ISC
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables safe, multi-account Gmail and Microsoft 365 operations with explicit aliases, including searching, reading, drafting, archiving, labels/categories, and human-reviewed sending via a localhost approval window.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to search, read, analyse, draft, and organise Gmail across multiple mailboxes, with sending strictly gated behind user approval.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to run real email operations across multiple IMAP/SMTP and provider OAuth accounts — syncing, searching, reading, drafting, attaching, and sending mail — while requiring explicit human approval for sending, deleting, or forwarding and recording an inspectable audit trail.
      Apache 2.0