gmail-mcp
This server lets an AI read and manage one Gmail mailbox — search, read messages/threads, handle labels, drafts, and send mail — all scoped to a single account.
Read mail: get mailbox profile and counts, search using Gmail's query syntax, fetch full messages or whole threads, list labels, attachments, and drafts.
Manage labels: list, create, delete labels, and add/remove labels on messages.
Organize messages: archive, mark read/unread, trash, or untrash messages.
Work with drafts: create, update, delete, and list/fetch drafts, optionally threading replies.
Send email: send an existing draft or compose-and-send in one step (destructive, reaches other people).
Page large results: retrieve more of any oversized result via
get_result_pagewith filtering, field selection, and paging.
Provides tools for reading and writing a Gmail mailbox, including searching messages, managing drafts and labels, archiving, trashing, and sending email.
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 create a draft reply to the email from Sarah about the project deadline"
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 second account MCP server
Read and write one Gmail mailbox from Claude.ai and Claude Code. Claude.ai's own Gmail connector handles a single account, so this exists for the second one: run an instance per mailbox and each connector reaches exactly the address it was given.
Using this server with a paid AI service costs money. Tool definitions and results are billed as input tokens, and an agent can call tools repeatedly on its own. You are responsible for every charge, so set spending limits with your provider. The author accepts no liability for any costs. SeeDISCLAIMER.md.
One mailbox per instance
Which account an instance serves comes from GMAIL_CREDENTIALS_DIR, and nothing else is reachable from that process. That separation is the point rather than a limitation: a draft cannot land in the wrong mailbox when the server only ever holds one set of credentials.
Related MCP server: Gmail MCP Local Server
Tools
Reading
Tool | What you get |
| Which mailbox this instance serves, and its counts |
| Search with Gmail's own query syntax |
| One message, with its body |
| A whole conversation, oldest first |
| Filenames, types and sizes on a message |
| Every label with its id |
| Drafts waiting in the mailbox |
Writing
Tool | What it does |
| Write a draft, optionally threaded as a reply |
| Replace a draft's contents |
| Discard a draft |
| Add or remove labels on a message |
| Take a message out of the inbox |
| Mark read or unread |
| Move to trash and back |
| Manage labels |
| Send an existing draft |
| Compose and send in one step |
The two send tools are marked destructive and say so in their descriptions: they reach other people and cannot be undone. The safe shape is gmail_create_draft, read it, then gmail_send_draft once a person has approved the text.
Searching
gmail_search takes the same operators as the Gmail search box:
is:unread from:client.com
subject:invoice has:attachment newer_than:7d
label:important -in:trashIt returns headers and a snippet per message rather than bodies, so a wide search stays small. Follow up with gmail_get_message or gmail_get_thread.
How it fits together
Claude.ai / Claude Code
| HTTPS
Cloudflare Tunnel, or any proxy that gives you HTTPS
|
nginx 127.0.0.1:8461
|
auth-server.js :8462 handles the login and the tokens
|
gmail-mcp :8460 the server itself, local only
|
gmail.googleapis.comThe MCP has no login of its own and refuses to listen on anything but the local machine, so everything reaching it has already passed the login.
Setup
You need a Google Cloud OAuth client with the Gmail API enabled, and a refresh token for the mailbox. The credentials directory holds two files:
credentials.json {"refresh_token": "..."}
gcp-oauth.keys.json the downloaded OAuth clientgmail.modify is the scope to grant. It covers reading, labelling, drafting and sending; drop to gmail.readonly plus gmail.compose if you would rather the credentials themselves could not send.
git clone https://github.com/rollecode/gmail-second-account-mcp.git
cd gmail-second-account-mcp
uv venv && uv pip install -e .
npm install --omit=dev
CONFIG_DIR=~/.config/gmail-mcp node set-password.js 'your-password-here'
openssl rand -hex 32 > ~/.config/gmail-mcp/token
chmod 600 ~/.config/gmail-mcp/tokenFill in YOUR_USER, the hostname and the credentials directory in systemd/*.service and nginx/gmail-mcp.conf, then:
sudo cp systemd/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now gmail-mcp gmail-mcp-auth
sudo cp nginx/gmail-mcp.conf /etc/nginx/sites-enabled/gmail-mcp
sudo nginx -t && sudo systemctl reload nginxPoint a tunnel or an HTTPS proxy at 127.0.0.1:8461. OAuth needs HTTPS.
Check from outside: discovery returns metadata, and /mcp without a token must return 401.
curl https://your-host/.well-known/oauth-authorization-server
curl -o /dev/null -w '%{http_code}\n' -X POST https://your-host/mcpConnecting
Claude.ai: Settings, Connectors, Add custom connector, https://your-host/mcp, client ID and secret blank.
Claude Code:
claude mcp add --transport http gmail https://your-host/mcp \
--header "Authorization: Bearer $(cat ~/.config/gmail-mcp/token)" --scope userLocally over stdio, with no server at all:
GMAIL_CREDENTIALS_DIR=/path/to/creds claude mcp add gmail -- /path/to/.venv/bin/gmail-mcpSettings
Variable | What it is for |
| Directory holding |
| Name for the mailbox, shown in the server's instructions |
| Public address, used to advertise the icon |
| Public origin of the login server |
| Login server port, 8462 by default |
| MCP server URL, |
| Where the password, token and OAuth database live |
Access tokens are refreshed in memory as they expire; only the refresh token is read from disk.
Credits
The login layer comes from rollecode/obsidian-remote-mcp.
Available Tools
21 toolsget_result_pageARead-onlyIdempotent
Read more of a result that was too large to return in one piece.
Any tool whose answer is too large returns its first page with a
paging block. Pass that block's result_id here. Nothing is fetched
again: the stored result is paged, filtered and narrowed.
Args:
result_id: From the paging block of the earlier answer.
offset: First item to return, usually the previous next_offset.
limit: At most this many items. Fewer come back if they would not fit.
fields: Only these keys of each item. Dots reach nested keys, such as
"statistics.sizeOnDisk". The paging.fields list shows what exists.
match: Keep only items whose field contains this text, ignoring case,
for example {"title": "alien", "year": "1979"}.
path: Which list to page when the result holds several, as named in
paging.lists. Defaults to the largest.
Inputs: result_id (required), path, limit, match, +2 more. Returns: result
gmail_archiveAIdempotent
Archive a message by taking it out of the inbox. Nothing is deleted.
Args: message_id: Message to archive.
Inputs: message_id (required). Returns: result
gmail_create_draftAIdempotent
Write a draft. It waits in the mailbox until a person sends it.
Passing reply_to_message_id threads the draft onto that message and sets the reply headers, so it appears in the conversation rather than as a new one.
Args: to: Recipient address, or several separated by commas. subject: Subject line. body: Plain text body. cc: Carbon copy addresses. bcc: Blind carbon copy addresses. reply_to_message_id: Message this replies to.
Inputs: to (required), body (required), subject (required), cc, +2 more. Returns: result
gmail_create_labelBIdempotent
Create a label. Use Parent/Child to nest it.
Args: name: Label name.
Inputs: name (required). Returns: result
gmail_delete_draftBDestructiveIdempotent
Discard a draft.
Args: draft_id: Draft to delete.
Inputs: draft_id (required). Returns: result
gmail_delete_labelADestructiveIdempotent
Delete a label. Messages keep their content but lose the label.
Args: label_id: Label id from gmail_list_labels.
Inputs: label_id (required). Returns: result
gmail_get_draftARead-onlyIdempotent
One draft in full, including its body.
Args: draft_id: Draft id from gmail_list_drafts.
Inputs: draft_id (required). Returns: result
gmail_get_messageARead-onlyIdempotent
One message in full, including its body text.
Args: message_id: Message id from gmail_search.
Inputs: message_id (required). Returns: result
gmail_get_threadARead-onlyIdempotent
A whole conversation, oldest message first.
Read this before replying: a thread's later messages often change what the first one asked for.
Args: thread_id: Thread id from gmail_search or gmail_get_message.
Inputs: thread_id (required). Returns: result
gmail_list_attachmentsARead-onlyIdempotent
What is attached to a message: filenames, types and sizes.
Args: message_id: Message id from gmail_search.
Inputs: message_id (required). Returns: result
gmail_list_draftsCRead-onlyIdempotent
Drafts waiting in the mailbox.
Args: limit: Maximum drafts to return, up to 100.
Inputs: limit. Returns: result
gmail_list_labelsARead-onlyIdempotent
Every label, with its id. Label ids are what the filing tools take.
Inputs: no named parameters. Returns: result
gmail_mark_readAIdempotent
Mark a message read, or unread with read=false.
Args: message_id: Message to mark. read: True marks it read, False marks it unread.
Inputs: message_id (required), read. Returns: result
gmail_modify_labelsAIdempotent
Add or remove labels on a message.
The system labels are INBOX, UNREAD, STARRED, IMPORTANT, SPAM and TRASH. Removing INBOX archives a message; removing UNREAD marks it read.
Args: message_id: Message to file. add: Label ids to add. remove: Label ids to remove.
Inputs: message_id (required), add, remove. Returns: result
gmail_profileARead-onlyIdempotent
Which mailbox this server serves, and how much is in it.
Worth calling first when more than one Gmail connector is set up, so a reply goes to the right account.
Inputs: no named parameters. Returns: result
gmail_searchARead-onlyIdempotent
Search the mailbox using Gmail's own query syntax.
Takes the same operators as the Gmail search box: from:, to:,
subject:, has:attachment, is:unread, label:, after:, before:,
newer_than:7d. An empty query lists the most recent mail.
Returns headers and a snippet per message, not bodies. Follow with gmail_get_message for one, or gmail_get_thread for the conversation.
Args: query: Gmail search expression, e.g. "is:unread from:client.com". limit: Maximum messages to return, up to 100. include_spam: Include spam and trash, which are excluded by default.
Inputs: limit, query, include_spam. Returns: result
gmail_send_draftADestructiveIdempotent
Send an existing draft. This reaches other people and cannot be undone.
Show the draft and get an explicit yes before calling this. Sending is not a step in a plan; it is the thing the person decides.
Args: draft_id: Draft to send.
Inputs: draft_id (required). Returns: result
gmail_send_messageADestructiveIdempotent
Compose and send in one step. This reaches other people immediately and cannot be undone.
Prefer gmail_create_draft, then gmail_send_draft once the text has been read and approved. Use this only when told to send outright.
Args: to: Recipient address, or several separated by commas. subject: Subject line. body: Plain text body. cc: Carbon copy addresses. bcc: Blind carbon copy addresses.
Inputs: to (required), body (required), subject (required), cc, +1 more. Returns: result
gmail_trashBDestructiveIdempotent
Move a message to the trash, where Gmail keeps it for 30 days.
Args: message_id: Message to trash.
Inputs: message_id (required). Returns: result
gmail_untrashAIdempotent
Take a message back out of the trash.
Args: message_id: Message to restore.
Inputs: message_id (required). Returns: result
gmail_update_draftAIdempotent
Replace a draft's contents. Gmail rewrites the whole message, so pass every field, not only the changed one.
Args: draft_id: Draft to replace. to: Recipient address. subject: Subject line. body: Plain text body. cc: Carbon copy addresses. bcc: Blind carbon copy addresses.
Inputs: to (required), body (required), subject (required), draft_id (required), +2 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools target distinct actions (search, get, draft, label, send). However, gmail_archive and gmail_mark_read are convenience wrappers that overlap with gmail_modify_labels, though the descriptions clearly steer usage. No severe confusion, but a few boundaries could be tighter.
Nearly all tools use a consistent gmail_ prefix with snake_case verb_noun structure. The lone exception is get_result_page, which breaks the prefix pattern and is a generic paging tool. This minor deviation keeps it from a perfect score.
21 tools is on the higher side but reasonable for full Gmail functionality including search, reading, labels, drafts, and sending. Each tool has a clear purpose, though a few convenience wrappers could be folded into gmail_modify_labels. Still well within acceptable scope for a complex domain.
Core email workflows are covered (search, read, draft, send, label, archive, trash). However, notable gaps exist: no way to download attachment content, and gmail_send_message and drafts lack attachment parameters, which will cause failures for common attachment tasks. Thread-level label operations are also missing.
Maintenance
Related MCP Connectors
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
Your mailboxes in ChatGPT and Claude: Gmail, iCloud, Fastmail, any IMAP. Passwords stay yours.
Connect Gmail, iCloud Mail, Outlook, Yahoo Mail, Fastmail and other IMAP inboxes to ChatGPT, Claude and compatible AI assistants. Find emails by meaning across languages with semantic search. Ask AI to find customer conversations, summarize deadlines and draft follow-ups. Give a sales rep access to a shared outreach inbox or bring email into a compatible CRM. Share an iCloud custom-domain inbox with teammates without their own Apple ID or iCloud+ plan. Search results may be incomplete or stale; separate permissions control mail actions.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables reading, sending, searching, and managing Gmail through Claude using the official Google Gmail API.3MIT
- FlicenseNot gradedqualityDmaintenanceProvides Claude with Gmail capabilities including sending emails, managing drafts, and searching messages.-
- FlicenseAqualityDmaintenanceEnables Claude to read, search, send, and manage Gmail messages and threads through natural language.13-
- AlicenseNot gradedqualityDmaintenanceEnables Gmail integration with Claude Code for reading, sending, searching emails, and managing labels through natural language.ISC