@theethosteam/gmail-mcp

Drafts-first MCP server and CLI for Gmail — create_draft / update_draft / list_drafts (the missing piece in the stock Gmail connector), plus search + read mail, threads, labels, and confirm-gated send — authenticated over OAuth as the mailbox owner. Runs via npx, identically locally or in a cloud session, because auth is a refresh token in env vars.

Built on the same pattern as the GA4 / GSC / GTM MCPs: one shared core/, exposed as both an MCP server (mcp.ts) and a commander CLI (cli.ts), run directly with tsx (no build step). Includes a generic raw tool so every users.* Gmail method is reachable.

Why this exists

The claude.ai Gmail connector can send and update an existing draft but cannot create one. The workflow we want is the opposite of send-on-behalf: the agent writes the email, stages it in the human's Drafts folder, and the human reads it and presses Send. So:

• create_draft is the primary tool — nothing leaves the mailbox. Returns a deep link straight into the compose window.
• Anything that actually sends (send_draft, send_message) is refused without confirm: true.
• Replies thread correctly: pass threadId + inReplyTo (the RFC messageId returned by get_message / get_thread).

Scopes: gmail.compose (drafts + send), gmail.readonly (search/read), gmail.modify (labels/archive). No delete scope.

One-time setup

1. Enable the Gmail API in the Google Cloud project that owns your Desktop OAuth client: https://console.cloud.google.com/apis/library/gmail.googleapis.com
2. OAuth client: reuse the existing Desktop app client (same as GA4/GSC/GTM) — client id + secret.
3. Mint a refresh token (this scope needs its own token):

   GMAIL_OAUTH_CLIENT_ID=… GMAIL_OAUTH_CLIENT_SECRET=… npx -y @theethosteam/gmail-mcp gmail auth:url
   # open the URL, approve, copy the ?code=… from the localhost redirect that fails to load
   GMAIL_OAUTH_CLIENT_ID=… GMAIL_OAUTH_CLIENT_SECRET=… npx -y @theethosteam/gmail-mcp gmail auth:exchange <code>

Env vars

GMAIL_OAUTH_CLIENT_ID · GMAIL_OAUTH_CLIENT_SECRET · GMAIL_OAUTH_REFRESH_TOKEN

Connect to Claude

Local (Claude Code CLI), every project:

claude mcp add gmail --scope user \
  -e GMAIL_OAUTH_CLIENT_ID=… -e GMAIL_OAUTH_CLIENT_SECRET=… -e GMAIL_OAUTH_REFRESH_TOKEN=… \
  -- npx -y @theethosteam/gmail-mcp

(Desktop app users: put the three vars in ~/.claude/settings.json env and register with an empty env: {} — the desktop app doesn't expand ${VAR}.)

Cloud (Claude Code on the web): .mcp.json with env via ${VAR}.

Tools

get_profile · create_draft · update_draft · list_drafts · get_draft · delete_draft† · send_draft† · search_messages · get_message · get_thread · list_labels · modify_message · send_message† · raw

† requires confirm: true.

CLI

gmail whoami
gmail search "from:[email protected] newer_than:7d" --body
gmail draft -t [email protected] -s "Subject" --body-file ./draft.txt
gmail draft -t [email protected] -s "Re: thing" --thread <threadId> --in-reply-to "<[email protected]>" -b "…"
gmail drafts
gmail draft:send <draftId> --confirm
gmail raw settings.sendAs.list