gmail-accounts
Provides multi-account Gmail integration allowing agents to search, read threads, list drafts, create and update drafts, and send emails with human-approved single-use tokens.
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-accounts search work for the invoice thread"
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 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
The agent stages a draft and asks you to approve it.
You run
gmail-approvein your own terminal, review the exact RFC822 payload, and get a one-time token bound to that draft's content hash.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.json2. 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 onesEach 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-mcpEveryday 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 tokenHealth check:
uv run gmail-mcp-healthSecurity notes
Secrets never enter the repo:
client_secret.jsonand per-account tokens live in~/.config/gmail-mcp/(override withGMAIL_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 pytestAvailable Tools
12 toolscreate_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_attachmentCRead-only
(unconfigured) Download one attachment to a path.
Inputs: account (required), save_path (required), message_id (required), attachment_id (required), +1 more.
get_messageCRead-only
(unconfigured) One message with bodies and attachment stubs.
Inputs: account (required), message_id (required).
get_threadBRead-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_accountsARead-only
(unconfigured) List configured accounts and local token state. Call this first.
Inputs: no named parameters.
list_draftsCRead-only
(unconfigured) List drafts.
Inputs: account (required).
list_labelsCRead-only
(unconfigured) List labels.
Inputs: account (required).
searchCRead-only
(unconfigured) Search a mailbox with Gmail query syntax.
Inputs: query (required), account (required), page_token, max_results, +1 more.
sendADestructive
(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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
Email inboxes for AI agents: send, receive, search, drafts with owner approval, and webhooks.
Email inboxes for AI agents: send, reply, read verification codes, human-approved drafts.
Governed email for AI agents: a sandbox inbox to read and send from, human approval to go external.
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Related MCP Servers
- AlicenseAqualityBmaintenanceConnects AI assistants to multiple Gmail accounts simultaneously, enabling search, read, draft, send, and reply operations with per-account permission controls.54ISC
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to search, read, analyse, draft, and organise Gmail across multiple mailboxes, with sending strictly gated behind user approval.MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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