gmail-multi-mcp
Provides tools for interacting with one or more Gmail accounts, including searching emails across accounts, reading messages and threads, listing labels, sending emails and threaded replies, creating drafts, modifying labels, marking messages read/unread, archiving, starring, and moving messages to Trash.
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-multi-mcp search all my accounts for unread emails from Amazon"
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-multi-mcp
An open-source MCP server that connects any number of Gmail accounts to Claude (or any MCP client) in one place. Everything runs locally, and your tokens never leave your machine.
Tools
Tool | What it does |
| Lists the connected accounts, with alias and read-only status |
| Runs a Gmail search query on one account or all of them at once |
| Reads one message or a whole conversation as plain text, with a list of attachments |
| Lists the labels for an account |
| Lists the addresses an account can send from (Gmail's "Send mail as") |
| Sends mail from a chosen account, including threaded replies. |
| Saves a draft instead of sending |
| Marks mail read or unread, archives, stars, or adds and removes labels |
| Moves a message to Trash (recoverable) |
Every tool takes an account argument, which can be the full email address or an alias such as work.
Sender addresses: if an account has extra addresses under Gmail's Settings → Accounts → Send mail as, send_email and create_draft can send from any of them with from_address. Without it, a reply goes out from the address the original was sent to, and a new mail goes out from Gmail's default sender.
Related MCP server: gmail-mcp
1. Create a Google OAuth client (once)
Open https://console.cloud.google.com/ and create a project.
APIs & Services → Library → enable the Gmail API.
APIs & Services → OAuth consent screen: choose External and fill in the app name and your email. Under Test users, add every Gmail address you want to connect.
APIs & Services → Credentials → Create credentials → OAuth client ID → Desktop app. Download the JSON file.
Save the file as
~/.config/gmail-multi-mcp/credentials.json.
Tip: while the app is in Testing status, Google expires refresh tokens after 7 days. For personal use you can click Publish app on the consent screen. It stays unverified, so you'll see an "unverified app" warning when you sign in, but the tokens stop expiring.
One OAuth client works for all your accounts.
2. Install
Install uv. It also installs Python for you:
curl -LsSf https://astral.sh/uv/install.sh | shThen install the server straight from GitHub:
uv tool install https://github.com/anitalklausen/gmail-multi-mcp/archive/refs/heads/main.zipTo install from a local clone instead, run uv tool install . in the project folder.
This puts gmail-multi-mcp in ~/.local/bin.
3. Connect accounts
Run this once per account. A browser opens where you choose the Google account:
gmail-multi-mcp add --alias private
gmail-multi-mcp add --alias work
gmail-multi-mcp add --alias shop --read-only
gmail-multi-mcp listRemove an account with gmail-multi-mcp remove work. New accounts are picked up by the running server without a restart.
4. Add it to Claude
Claude Desktop: go to Settings → Developer → Edit Config and add the server to claude_desktop_config.json:
{
"mcpServers": {
"gmail": {
"command": "/Users/YOUR_USERNAME/.local/bin/gmail-multi-mcp"
}
}
}Use the absolute path, because Claude Desktop does not read your shell's PATH. Restart Claude Desktop afterwards.
Claude Code:
claude mcp add gmail --scope user -- ~/.local/bin/gmail-multi-mcpConfiguration
Environment variable | Effect |
| Config/token folder. The default is |
| Path to the OAuth client JSON |
| Hides every write tool (send, draft, labels, trash) for all accounts |
Security
Tokens are stored in
tokens/<email>.jsonwith600permissions. Treat them like passwords.The default scope is
gmail.modify: read, send, and change labels, but never permanent deletion. Accounts added with--read-onlygetgmail.readonly.The server tells the model to confirm with you before sending, and Claude also asks for approval on every tool call.
See also the privacy policy.
License
MIT
Available Tools
9 toolscreate_draftB
Save an email as a draft in the given account (not sent).
Inputs: to (required), body (required), account (required), subject (required), +3 more.
list_accountsA
List all connected Gmail accounts with their alias and read-only status.
Inputs: no named parameters. Returns: result
list_labelsC
List labels (system and user-created) for an account.
Inputs: account (required). Returns: result
modify_labelsB
Add/remove labels by name or id. Examples: mark read = remove ['UNREAD']; archive = remove ['INBOX']; star = add ['STARRED'].
Inputs: account (required), message_id (required), add_labels, remove_labels.
read_emailB
Read one email in full (headers, plain-text body, attachment list).
Inputs: account (required), message_id (required), max_body_chars.
read_threadC
Read every message in a conversation thread, oldest first.
Inputs: account (required), thread_id (required), max_body_chars. Returns: result
search_emailsA
Search email using Gmail search syntax (e.g. 'is:unread from:bob newer_than:7d').
Args: query: Gmail search query. Empty returns the newest messages. account: Email or alias. Omit to search ALL connected accounts. max_results: Max messages per account (1-50).
Inputs: query, account, max_results.
send_emailA
Send an email from the given account. Confirm content with the user first.
Args: account: Sender account (email or alias). to: Comma-separated recipients. subject: Subject. May be empty when replying (uses 'Re: '). body: Plain-text body. reply_to_message_id: Message id to reply to; keeps the thread intact.
Inputs: to (required), body (required), account (required), subject (required), +3 more.
trash_emailB
Move a message to Trash (recoverable for 30 days).
Inputs: account (required), message_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a fairly distinct purpose: reading, searching, sending, drafting, trashing, and label management are all clearly separated. The only mild overlap is between modify_labels (which can apply TRASH/UNREAD labels) and trash_email, plus list_labels vs modify_labels, but descriptions make the intended use clear.
All nine tools follow a strict verb_noun snake_case pattern (list_accounts, search_emails, read_email, read_thread, list_labels, modify_labels, trash_email, send_email, create_draft). No camelCase or vague verbs mixed in.
Nine tools is a well-scoped surface for a multi-account Gmail server, covering the core mailbox operations without bloat. Every tool maps to a distinct mailbox workflow.
Core lifecycle is well covered: list/search/read/read thread, send, draft, trash, and label management across accounts. Minor gaps remain — no attachment download, no permanent delete (only trash), and no explicit forward or mark-spam/unspam tool, though these can be approximated with existing tools.
Maintenance
Related MCP Connectors
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that enables Claude Desktop to interact with Gmail through secure OAuth 2.0 authentication. Send emails, search messages, read emails, and manage multiple Gmail accounts directly from Claude Desktop.298 npmMIT
- AlicenseNot gradedqualityCmaintenanceConnects Gmail to Claude and other MCP clients so an assistant can search and read mail, send, reply-all with quoted history, forward, handle attachments and inline images, and manage drafts, labels, and threads. Runs as a remote server on your own Cloudflare Worker, serving several Google accounts simultaneously to desktop, browser, and phone clients while you retain the refresh tokens.MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude to search and read multiple Gmail or Google Workspace mail accounts at once through a local, read-only MCP server, with every result labeled by the account it came from. Tokens stay in the OS keychain, no server is run by the authors, and write actions such as sending, deleting, or archiving are not supported.12 npm1AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceConnects several Gmail and Google Workspace accounts to MCP-capable AI apps so they can search, read, draft, send, reply, and label mail across one account or all of them at once. Runs locally on Windows with encrypted on-disk credentials, no delete tools, and approval-gated sending.MIT