Gmail MCP server
About
A super simple and tiny MCP server for gmail in python
Details
- Author
- pliablepixels
- Categories
- Communication, Other, Automation, Productivity
Jump to
Install (Gmail API backend — recommended)
-In](https://myaccount.google.com/apppasswords)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 typeDesktop appand 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.json
Register the MCP server with Claude Code (no env vars needed):
claude mcp add gmail --scope user -- uvx claude-gmail-mcp
claude mcp add gmail --scope user \ -e GMAIL_ADDRESS=you@gmail.com \ -e GMAIL_APP_PASSWORD=your-app-password \ -- uvx claude-gmail-mcp
Replaceyou@gmail.comandyour-app-passwordwith your actual credentials. Drop--scope userto install only for the current project directory.
You should seegmaillisted as a configured server. To see which backend is active, run:
uvx claude-gmail-mcp 2>&1 | head -1
Expected:[gmail-mcp] backend=apior[gmail-mcp] backend=imap. Ctrl-C to exit.
At startup the server picks exactly one backend:
- Token file atGMAIL_TOKEN_PATH(default~/.config/claude-gmail-mcp/token.json) exists →API backend.
- ElseGMAIL_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, setGMAIL_TOKEN_PATHto a non-existent path (or delete the token file).
Send an email toalice@example.comwith subject "Hello" and body "Hi from Claude!"
- 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.
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.
Send an email toalice@example.comwith subject "Report" and attach ~/Documents/report.pdf
python -m build && twine upload dist/*
git clone https://github.com/pliablepixels/claude-gmail-mcp.git cd claude-gmail-mcp uv sync uv run pytest
Test 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=....)
Query live Gmail data using LLMs via CData's read-only MCP server.
Search and delete emails in your Gmail account.
Enables AI assistants to manage Gmail through natural language interactions.
A standardized interface for managing, sending, and retrieving emails through the Gmail API.
Manage your Gmail account, including sending, reading, and organizing emails.
Allows AI agents to search Gmail threads, learn your writing style, and draft emails.
An MCP server that enables AI models to interact directly with the Gmail API to manage emails.
An MCP server for integrating with the Gmail API to manage emails.
Most email MCP servers only read from IMAP. mail-mcp does everything: 30 tools for reading, searching, sending, replying, forwarding, and bulk operations across IMAP, SMTP, Microsoft Graph API, and Exchange Web Services. Multi-account, native OAuth2, built in Rust. Works with Gmail, Microsoft 365, Hotmail/Outlook.com, Zoho, and any standard IMAP/SMTP server.
MCP server for structured, read-only email access. Exposes a minimal, auditable API surface — AI agents can search and read emails, but cannot send, delete, or modify your mailbox.
A super simple and tiny MCP server for gmail in python
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
- A Google Cloud OAuth client (Desktop app) — for the API backend, OR
- A GmailApp Password— for the SMTP/IMAP backend
Install (Gmail API backend — recommended)
-Run the auth helper, pointing at the downloaded file:
uvx --from claude-gmail-mcp claude-gmail-mcp-auth /path/to/credentials.json
Register the MCP server with Claude Code (no env vars needed):
claude mcp add gmail --scope user -- uvx claude-gmail-mcp
claude mcp add gmail --scope user \ -e GMAIL_ADDRESS=you@gmail.com \ -e GMAIL_APP_PASSWORD=your-app-password \ -- uvx claude-gmail-mcp
Replaceyou@gmail.comandyour-app-passwordwith your actual credentials. Drop--scope userto install only for the current project directory.
You should seegmaillisted as a configured server. To see which backend is active, run:
uvx claude-gmail-mcp 2>&1 | head -1
Expected:[gmail-mcp] backend=apior[gmail-mcp] backend=imap. Ctrl-C to exit.
At startup the server picks exactly one backend:
- Token file atGMAIL_TOKEN_PATH(default~/.config/claude-gmail-mcp/token.json) exists →API backend.
- ElseGMAIL_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, setGMAIL_TOKEN_PATHto a non-existent path (or delete the token file).
Send an email toalice@example.comwith subject "Hello" and body "Hi from Claude!"
- 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.
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.
Send an email toalice@example.comwith subject "Report" and attach ~/Documents/report.pdf
python -m build && twine upload dist/*
git clone https://github.com/pliablepixels/claude-gmail-mcp.git cd claude-gmail-mcp uv sync uv run pytest
Test 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=....)
Query live Gmail data using LLMs via CData's read-only MCP server.
Search and delete emails in your Gmail account.
Enables AI assistants to manage Gmail through natural language interactions.
A standardized interface for managing, sending, and retrieving emails through the Gmail API.
Manage your Gmail account, including sending, reading, and organizing emails.
Allows AI agents to search Gmail threads, learn your writing style, and draft emails.
An MCP server that enables AI models to interact directly with the Gmail API to manage emails.
An MCP server for integrating with the Gmail API to manage emails.
Most email MCP servers only read from IMAP. mail-mcp does everything: 30 tools for reading, searching, sending, replying, forwarding, and bulk operations across IMAP, SMTP, Microsoft Graph API, and Exchange Web Services. Multi-account, native OAuth2, built in Rust. Works with Gmail, Microsoft 365, Hotmail/Outlook.com, Zoho, and any standard IMAP/SMTP server.
MCP server for structured, read-only email access. Exposes a minimal, auditable API surface — AI agents can search and read emails, but cannot send, delete, or modify your mailbox.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
