claude-gmail-mcp
Allows sending, searching, and reading Gmail messages through the Gmail API or SMTP/IMAP.
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., "@claude-gmail-mcp Send an email to mom@example.com saying I'll be late"
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.
claude-gmail-mcp
A super tiny Gmail MCP server for Claude Code. Lets Claude send, search, and read Gmail on your behalf.
Two backends are supported and auto-selected at startup:
Gmail API (OAuth) — recommended. No app password. Batch search. Direct Gmail web URLs on every result.
SMTP/IMAP (app password) — simpler setup. Fallback when the OAuth token isn't present.
I needed something for my projects — there were a bunch around which seemed super complicated. So why not have Claude CLI build one for me :-p
Prerequisites
uv installed
One of:
A Google Cloud OAuth client (Desktop app) — for the API backend, OR
A Gmail App Password — for the SMTP/IMAP backend
Related MCP server: gmail-mcp
Install (Gmail API backend — recommended)
In Google Cloud Console, create a project, enable the Gmail API, and configure the OAuth consent screen (External, add your Gmail as a test user). Create an OAuth client of type Desktop app and download the credentials JSON.
Run the auth helper, pointing at the downloaded file:
uvx --from claude-gmail-mcp claude-gmail-mcp-auth /path/to/credentials.jsonBrowser opens → sign in → approve (scope:
gmail.modify). Refresh token is saved to~/.config/claude-gmail-mcp/token.json(perms600).Register the MCP server with Claude Code (no env vars needed):
claude mcp add gmail --scope user -- uvx claude-gmail-mcp
Install (SMTP/IMAP backend — fallback)
claude mcp add gmail --scope user \
-e GMAIL_ADDRESS=you@gmail.com \
-e GMAIL_APP_PASSWORD=your-app-password \
-- uvx claude-gmail-mcpReplace you@gmail.com and your-app-password with your actual credentials. Drop --scope user to install only for the current project directory.
Verify
claude mcp listYou should see gmail listed as a configured server. To see which backend is active, run:
uvx claude-gmail-mcp 2>&1 | head -1Expected: [gmail-mcp] backend=api or [gmail-mcp] backend=imap. Ctrl-C to exit.
Backend selection
At startup the server picks exactly one backend:
Token file at
GMAIL_TOKEN_PATH(default~/.config/claude-gmail-mcp/token.json) exists → API backend.Else
GMAIL_ADDRESS+GMAIL_APP_PASSWORDenv vars set → IMAP backend.Else tools return a "no backend configured" error.
To force a switch to the IMAP backend when a token file exists, set GMAIL_TOKEN_PATH to a non-existent path (or delete the token file).
Usage
Ask Claude to send an email:
Send an email to alice@example.com with subject "Hello" and body "Hi from Claude!"
Tools exposed:
send_email—to,subject,body, optionalcc/bcc,html,attachments(local file paths; unreadable files are skipped with a warning).search_emails—queries(single string or list of strings),max_results(per query when a list is passed). Results include the Gmail message ID in hex and a direct Gmail web URL per hit.read_email—uid(the hex ID fromsearch_emails). Output includes the Gmail web URL at the top.
Batch search example:
Search Gmail for "is:unread from:alice" and "is:unread from:bob" — show me both side by side.
Claude passes both queries in a single tool call. The response is sectioned per query. API backend executes the list step in one HTTP roundtrip; IMAP backend iterates.
Attachment example:
Send an email to alice@example.com with subject "Report" and attach ~/Documents/report.pdf
Publishing to PyPI
python -m build && twine upload dist/*For Development
git clone https://github.com/pliablepixels/claude-gmail-mcp.git
cd claude-gmail-mcp
uv sync
uv run pytestRun the server locally:
uv run claude-gmail-mcpTest with Claude Code using your local copy instead of the published package:
claude mcp add gmail --scope user \
-- uv run --directory /path/to/claude-gmail-mcp claude-gmail-mcp(For the IMAP backend add -e GMAIL_ADDRESS=... -e GMAIL_APP_PASSWORD=....)
Available Tools
3 toolsread_emailA
Fetch the full content of an email by its UID (from search_emails results).
Args: uid: Email UID shown in search_emails output
Inputs: uid (required). Returns: result
search_emailsA
Search Gmail using full Gmail search syntax (from:, subject:, is:unread, etc).
Pass a single query string for a flat list of results, or a list of queries to run several searches in one call (output is sectioned by query, and max_results applies per query).
Returns UID, sender, subject, date, and a Gmail web URL for each match.
Args: queries: Single query string or list of query strings. max_results: Max emails to return per query (default 10).
Inputs: queries (required), max_results. Returns: result
send_emailA
Send an email via Gmail.
Args: to: Recipient email address(es). subject: Email subject line. body: Email body content (plain text or HTML). cc: CC recipient(s), optional. bcc: BCC recipient(s), optional. html: If True, send body as HTML instead of plain text. attachments: List of local file paths to attach, optional. Files that cannot be read are skipped with a warning.
Inputs: to (required), subject (required), body (required), cc, +3 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 3 tools
Each tool has a clearly distinct purpose: reading, searching, and sending emails. There is no overlap in functionality, making it easy for an agent to select the correct tool.
All tools follow a consistent verb_noun pattern (read_email, search_emails, send_email), ensuring predictability and ease of use.
With only 3 tools, the set is minimal but covers the core email operations. While slightly under-scoped, it is still reasonable for a focused MCP server.
The tools cover essential read, search, and send operations, but lack common Gmail features like deleting, labeling, or managing drafts, which are notable gaps for a full email client.
Maintenance
Related MCP Connectors
A MCP server for Gmail that lets you search, read, and draft emails and replies.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Related MCP Servers
- AlicenseBqualityFmaintenanceMCP server that connects Claude with Gmail to read, send, delete, and manage messages and labels via the Google Gmail API.3MIT
- AlicenseAqualityCmaintenanceAn MCP server that lets Claude read, search, send, label, and manage your Gmail through OAuth2.25MIT
- AlicenseNot gradedqualityDmaintenanceA local MCP server that provides tool-level access to Gmail, allowing Claude to search, read, send, and manage emails using the Gmail API.1MIT
- FlicenseNot gradedqualityDmaintenanceA secure MCP server that enables Claude to read, search, send, reply, forward, and manage Gmail messages and labels through natural language commands.1-