gmail-mcp
Provides tools for interacting with a Gmail account, including searching messages and threads, managing drafts, sending, replying, forwarding, handling attachments, labels, and trash/spam operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gmail-mcp Find the latest email from my bank and save the attached statement to ~/Downloads."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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,replyandforwardtake file paths. The official server only accepts base64 in the tool call, which is unusable for a multi‑megabyte PDF.Attachment download.
list_attachmentsandsave_attachmentswrite 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_draftkeeps existing attachments and threading unless told otherwise;delete_draftandsend_draftexist.Replies and forwards as drafts.
replyandforwardcompute Gmail's default recipients, quote the original, re‑attach forwarded files, and takeasDraft: truewhen the user should review before sending.Message-level search (
search_messages) next to thread search,get_profile,get_labelwith counts,update_thread_labels, andbatch_modify_messagesfor 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)
In Google Cloud Console create or pick a project.
APIs & Services → Library: enable the Gmail API.
Google Auth Platform → Get started: fill in the app name and your email, choose External.
Data Access → Add or remove scopes: add
https://www.googleapis.com/auth/gmail.modifyandhttps://www.googleapis.com/auth/gmail.settings.basic.Audience: add yourself under Test users.
Clients → Create client, type Desktop app. Download the JSON and save it as
~/.config/gmail-mcp/credentials.json.Publish the app (recommended). While the app is in Testing, Google expires refresh tokens after 7 days and you would have to run
authweekly. Under Branding, set the home page tohttps://github.com/gchallen/gmail-mcp, the privacy policy tohttps://github.com/gchallen/gmail-mcp/blob/main/PRIVACY.md, and addgithub.comas 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 statusOr without cloning (the built dist/ is committed):
bunx --bun gchallen/gmail-mcp auth
# or
npx gchallen/gmail-mcp authtoken.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-mcpEquivalent ~/.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).
File | Purpose |
| OAuth client from Google Cloud Console |
| Refresh token written by |
| Optional: |
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 clientComparison with the claude.ai Gmail connector
Official (hosted) | gmail-mcp | |
Runs | Google's servers, via claude.ai connector auth | Locally, any machine with |
Attachments out | base64 in the tool call only | Local file paths (or base64) |
Attachments in | Metadata only | Download to disk |
Signature | None | Appended, hyperlinked, de-duplicated |
Update draft | Drops attachments | Keeps them unless replaced |
Delete draft | No | Yes |
Reply / forward | Send only | Send or draft; forwards carry attachments |
Bulk label changes | No |
|
Labels by name | No (IDs only) | IDs or names |
CLI | No | Yes |
License
MIT
Available Tools
38 toolsapply_sensitive_message_labelADestructive
Compatibility alias for the official server: TRASH or SPAM one message. Prefer trash_message / mark_message_spam.
Inputs: messageId (required), labelOption (required).
apply_sensitive_thread_labelADestructive
Compatibility alias for the official server: TRASH or SPAM a whole thread. Prefer trash_thread / mark_thread_spam.
Inputs: threadId (required), labelOption (required).
batch_modify_messagesADestructive
Bulk label change: over a list of message IDs, or over every message matching a Gmail query (up to maxMessages, default 500). Built for triage such as archiving a newsletter's backlog (query "from:news@x.com", removeLabelIds ["INBOX"]) or marking a search read. Returns the count and IDs touched.
Inputs: query, messageIds, addLabelIds, maxMessages, +1 more.
create_draftA
Create a draft. With replyToMessageId it becomes a reply in that thread (subject, In-Reply-To and References set; the original is quoted below the new text unless quote is false); recipients are still yours to give, or use reply with asDraft for Gmail's default recipients. Attachments are local file paths. Returns the draft ID, message ID, thread ID and a Gmail link.
Inputs: cc, to, bcc, body, +6 more.
create_labelA
Create a label. Nested labels use "/" (Projects/Alpha); missing parents are created unless autoCreateParents is false. Color by preset name or by hex pair from Gmail's palette.
Inputs: name (required), textColor, colorPreset, backgroundColor, +3 more.
delete_draftADestructive
Discard a draft permanently by draft ID. Does not affect the thread it belongs to.
Inputs: draftId (required).
delete_labelADestructive
Delete a user label. Messages keep their other labels. System labels cannot be deleted.
Inputs: labelId (required).
forwardA
Forward a message: your comment on top, then the standard "Forwarded message" block with the original headers and body, with the original attachments re-attached (includeAttachments false to drop them). Subject prefixed with Fwd:. Sends immediately unless asDraft is true.
Inputs: to (required), messageId (required), cc, bcc, +6 more.
get_draftARead-only
Read a draft by draft ID (not message ID): recipients, subject, body, attachments and a Gmail link.
Inputs: draftId (required), format.
get_labelBRead-only
One label with its message and thread counts (total and unread).
Inputs: labelId (required).
get_messageARead-only
Read one message by ID: headers, labels, attachment list and body. Not for drafts; use get_draft for those.
Inputs: messageId (required), format.
get_profileARead-only
The authenticated account: email address, total message and thread counts, current history ID. Use it to learn whose mailbox this is.
Inputs: no named parameters.
get_threadARead-only
Read a whole conversation: every message in the thread, oldest first, with bodies. Drafts in the thread are included as messages with the DRAFT label.
Inputs: threadId (required), format.
label_messageA
Add labels to one message. IDs or exact names; system labels too (STARRED, IMPORTANT, INBOX, UNREAD). Use trash_message or mark_message_spam for those states.
Inputs: labelIds (required), messageId (required).
label_threadA
Add labels to every message in a thread (and, for user labels, future messages in it).
Inputs: labelIds (required), threadId (required).
list_attachmentsBRead-only
List the attachments on a message: filename, MIME type, size, attachment ID, and whether it is an inline image.
Inputs: messageId (required).
list_draftsARead-only
List drafts, newest first, with draft IDs. Filter with a Gmail query. view "full" adds bodies.
Inputs: view, query, pageToken, maxResults.
list_labelsARead-only
All labels with IDs, names, type (system or user), colors and visibility. System labels: INBOX, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, TRASH, SPAM, CATEGORY_*. Label tools accept either an ID or an exact name.
Inputs: no named parameters.
mark_message_spamBDestructive
Mark one message as spam (adds SPAM, removes INBOX).
Inputs: messageId (required).
mark_thread_spamCDestructive
Mark a whole thread as spam.
Inputs: threadId (required).
replyA
Reply to a message with Gmail's default recipients: the sender (or Reply-To), plus everyone on To and Cc except yourself when replyAll is true. Threaded, subject prefixed with Re:, original quoted below, signature appended. Sends immediately unless asDraft is true, which leaves a draft to review. to/cc/bcc override the defaults.
Inputs: messageId (required), cc, to, bcc, +7 more.
save_attachmentsA
Download attachments from a message to a local directory and return the written paths. All regular attachments by default; narrow with filenameContains or attachmentId. Existing files are not overwritten unless overwrite is set (a numbered copy is written instead).
Inputs: directory (required), messageId (required), overwrite, attachmentId, +2 more.
search_messagesARead-only
Search individual messages rather than threads: one row per message with headers, snippet and labels. Better than search_threads when you need a specific message ID (to reply, forward, label or fetch attachments) or a date-ordered list.
Inputs: query, format, labelIds, pageToken, +2 more.
search_threadsARead-only
Search conversations (threads). Returns one row per thread: subject, snippet, participants, message count, last date, label IDs and message IDs, without bodies. Use get_thread to read one. Drafts-only threads are excluded unless the query mentions drafts. An empty list means nothing matched.
Inputs: view, query, labelIds, pageToken, +2 more.
send_draftB
Send an existing draft as-is. Returns the sent message ID and thread ID.
Inputs: draftId (required).
send_messageA
Send a new message immediately. To thread it into an existing conversation give replyToMessageId (quotes and threads on that message) or replyThreadId (threads only). To send a draft instead, give draftId and nothing else. For replies with Gmail's default recipients use the reply tool. Prefer create_draft when the user should review first.
Inputs: cc, to, bcc, body, +8 more.
trash_messageADestructive
Move one message to Trash (also works on a draft's message ID). Prefer trash_thread for whole conversations.
Inputs: messageId (required).
trash_threadBDestructive
Move every message in a thread to Trash.
Inputs: threadId (required).
unlabel_messageA
Remove labels from one message. Removing INBOX archives it; removing UNREAD marks it read.
Inputs: labelIds (required), messageId (required).
unlabel_threadA
Remove labels from every message in a thread. Removing INBOX archives the conversation; removing UNREAD marks it read.
Inputs: labelIds (required), threadId (required).
unmark_message_spamA
Un-spam one message (removes SPAM, restores INBOX).
Inputs: messageId (required).
unmark_thread_spamC
Un-spam a whole thread.
Inputs: threadId (required).
untrash_messageB
Restore one message from Trash.
Inputs: messageId (required).
untrash_threadB
Restore every message in a thread from Trash.
Inputs: threadId (required).
update_draftA
Edit an existing draft. Only the fields given change; recipients, subject, threading and attachments are kept otherwise. Giving body or htmlBody replaces the whole body (including any quoted original), and the signature is re-appended. Giving attachments replaces the attachment set; clearAttachments removes them all. Note the draft's message ID changes on every update while the draft ID stays the same.
Inputs: draftId (required), cc, to, bcc, +6 more.
update_labelB
Rename a label or change its color or visibility.
Inputs: labelId (required), name, textColor, colorPreset, +3 more.
update_message_labelsA
Add and remove labels on one message in a single call, e.g. move between labels or mark read and archive at once.
Inputs: messageId (required), addLabelIds, removeLabelIds.
update_thread_labelsB
Add and remove labels on a whole thread in one call.
Inputs: threadId (required), addLabelIds, removeLabelIds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 38 tools
Many tools have genuinely distinct scope (drafts vs. search vs. attachments), but there is real overlap: update_message_labels/update_thread_labels fully subsume label_message/unlabel_message and their thread counterparts, send_message can send a draft (draftId) duplicating send_draft, and create_draft(replyToMessageId)/reply(asDraft)/send_message all produce threaded replies. The two apply_sensitive_*_label tools are explicitly acknowledged aliases for trash/mark-spam tools, which is a direct purpose collision. Descriptions do give guidance ("prefer X over Y"), which keeps it from being worse.
Nearly everything follows a verb_noun snake_case pattern (create_draft, get_thread, trash_message, list_labels) with a clear message/thread parallel. Minor deviations are batch_modify_messages (verb-first adverbial) and the alias-style apply_sensitive_message_label, but the overall convention is predictable.
38 tools is heavy for a mailbox server, and a sizable chunk is redundant: paired label/unlabel plus update_* variants at both message and thread level, and two alias tools. The remaining surface (drafts, send/reply/forward, search, attachments, labels, trash/spam) is defensible, but the set exceeds what the scope warrants.
Coverage is broad: full draft lifecycle, send/reply/forward, message and thread reads, search, attachments download, label CRUD, label mutation, batch modify, trash and spam at both message and thread granularity. Gaps are minor/administrative — no permanent delete, attachment fetching by ID returning content inline, filters/settings, or profile-adjacent account management — which agents can work around.
Maintenance
Related MCP Connectors
Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflow…
Give AI agents their own email inboxes: list, read and send mail via scoped, revocable OAuth grants.
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Manage Gmail messages, threads, labels, drafts, and settings from your workflows. Send and organiz…
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides access to Gmail functionality through the Model Context Protocol, allowing LLMs like Claude to interact with your email.2-
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to manage Gmail through natural language, including search, read, send, label, and draft operations via the Model Context Protocol.-
- AlicenseNot gradedqualityDmaintenanceEnables Gmail integration with Claude Code for reading, sending, searching emails, and managing labels through natural language.313 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to send, read, search, and manage Gmail emails, drafts, and labels via the Model Context Protocol.5MIT