gmail-mcp

A Model Context Protocol server for one Gmail account, built for Claude Code. It talks to the Gmail API directly with a locally stored OAuth token, so it runs on any machine you sign in on and needs no hosted connector.

It is a superset of Google's hosted Gmail MCP server (gmailmcp.googleapis.com, the one behind the claude.ai Gmail connector): every tool there has a counterpart here with the same name and parameters, plus the things that server cannot do because it lives in the cloud.

What it adds over the official server

• Attachments from local files. create_draft, send_message, reply and forward take file paths. The official server only accepts base64 in the tool call, which is unusable for a multi‑megabyte PDF.

• Attachment download. list_attachments and save_attachments write files to a directory of your choice.

• A signature that survives. The configured signature (or the one in your Gmail settings) is appended to every outgoing message as a real hyperlink, once, even if the caller typed it.

• Drafts you can iterate on. update_draft keeps existing attachments and threading unless told otherwise; delete_draft and send_draft exist.

• Replies and forwards as drafts. reply and forward compute Gmail's default recipients, quote the original, re‑attach forwarded files, and take asDraft: true when the user should review before sending.

• Message-level search (search_messages) next to thread search, get_profile, get_label with counts, update_thread_labels, and batch_modify_messages for query-driven bulk triage.

• Labels by name. Every label parameter accepts a label ID or its exact name.

• A CLI. gmail-mcp call <tool> '<json>' runs any tool from a shell, handy for scripts and debugging.

Bodies are plain text by default (one line per paragraph). Every message goes out as multipart/alternative with an HTML part derived from the text, so URLs and the signature are real links even after a URL-rewriting gateway (Proofpoint URL Defense and the like) has been at them. Pass htmlBody for lists or other formatting; the plain-text alternative is derived automatically.

Related MCP server: Gmail MCP Server

Setup

1. Create an OAuth client (once, reusable on every machine)

1. In Google Cloud Console create or pick a project.

2. APIs & Services → Library: enable the Gmail API.

3. Google Auth Platform → Get started: fill in the app name and your email, choose External.

4. Data Access → Add or remove scopes: add https://www.googleapis.com/auth/gmail.modify and https://www.googleapis.com/auth/gmail.settings.basic.

5. Audience: add yourself under Test users.

6. Clients → Create client, type Desktop app. Download the JSON and save it as ~/.config/gmail-mcp/credentials.json.

7. Publish the app (recommended). While the app is in Testing, Google expires refresh tokens after 7 days and you would have to run auth weekly. Under Branding, set the home page to https://github.com/gchallen/gmail-mcp, the privacy policy to https://github.com/gchallen/gmail-mcp/blob/main/PRIVACY.md, and add github.com as an authorized domain. Then Audience → Publish app. Verification is not needed for personal use: sign-in shows a "Google hasn't verified this app" warning you click through under Advanced, and unverified apps are limited to 100 users.

The scopes requested are gmail.modify (everything except permanent deletion) and gmail.settings.basic (to read your signature).

2. Install and sign in

From a clone:

git clone https://github.com/gchallen/gmail-mcp.git ~/code/gmail-mcp
cd ~/code/gmail-mcp
bun install          # or npm install
bun src/cli.ts auth  # opens a browser; writes ~/.config/gmail-mcp/token.json
bun src/cli.ts status

Or without cloning (the built dist/ is committed):

bunx --bun gchallen/gmail-mcp auth
# or
npx gchallen/gmail-mcp auth

token.json holds a refresh token tied to your OAuth client. To set up a second machine, either run auth there or copy ~/.config/gmail-mcp/ across; both files are secrets, keep them out of git.

3. Register with Claude Code

claude mcp add --scope user gmail -- node ~/code/gmail-mcp/bin/cli.js
# or, with no clone on the machine:
claude mcp add --scope user gmail -- npx -y gchallen/gmail-mcp

Equivalent ~/.claude.json entry:

"gmail": { "type": "stdio", "command": "node", "args": ["/Users/you/code/gmail-mcp/bin/cli.js"] }

4. Turn off the claude.ai Gmail connector (optional)

If your claude.ai account has the Gmail connector attached, Claude Code loads it in every session alongside this server. Its tools have the same names, which is confusing. claude mcp remove cannot touch account connectors, and the /mcp menu only disables them per project. To block it for every project on the machine, add this to ~/.claude/settings.json:

"deniedMcpServers": [{ "serverName": "claude.ai Gmail" }]

The connector stays attached to your claude.ai account and keeps working there; only Claude Code on this machine stops loading it.

Configuration

Everything lives in ~/.config/gmail-mcp/ (override the directory with GMAIL_MCP_DIR, which is also how you run a second account).

Signature precedence: GMAIL_SIGNATURE / GMAIL_SIGNATURE_HTML environment variables, then config.json, then the signature configured in Gmail settings for your primary address, then none. Set appendSignature: false (or GMAIL_APPEND_SIGNATURE=false) to disable. Any tool that composes mail also takes signature: false per call.

CLI

gmail-mcp                       start the MCP server on stdio
gmail-mcp auth [--force]        sign in; --force re-consents (needed after a scope change)
gmail-mcp status                config dir, token state, account, signature in use
gmail-mcp tools                 list tools and parameters
gmail-mcp call <tool> '<json>'  run one tool, e.g.
    gmail-mcp call search_threads '{"query":"is:unread newer_than:2d","maxResults":5}'
    gmail-mcp call save_attachments '{"messageId":"18f...","directory":"~/Downloads/x"}'

Tools

Reading: get_profile, search_threads, search_messages, get_message, get_thread, list_attachments, save_attachments

Drafts: create_draft, update_draft, get_draft, list_drafts, delete_draft, send_draft

Sending: send_message, reply, forward

Labels: list_labels, get_label, create_label, update_label, delete_label, label_message, unlabel_message, update_message_labels, label_thread, unlabel_thread, update_thread_labels, batch_modify_messages

Trash and spam: trash_message, untrash_message, trash_thread, untrash_thread, mark_message_spam, unmark_message_spam, mark_thread_spam, unmark_thread_spam, and the official server's apply_sensitive_message_label / apply_sensitive_thread_label aliases.

Message format values: plain_text (default), full (adds htmlBody), minimal, metadata, raw.

Search queries use Gmail's own syntax (from:, subject:, newer_than:7d, has:attachment, label:, in:, is:unread, quotes, OR, -).

Development

bun test              # unit tests for MIME building, signatures, parsing
bun run typecheck
bun run build         # emits dist/ (committed so npx/bunx work from GitHub)
bun test/mcp-smoke.ts # drives the built server over stdio like a real client

Comparison with the claude.ai Gmail connector

License

MIT