Enables AI agents to search, read, manage drafts, and handle email attachments directly through the Gmail API.
Also known as dremok/gmail-agent
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.3.1
- Last commit
- Oct 11, 2026
- License
- MIT
What is gmail-agent MCP?
gmail-agent enables AI agents to search, read, manage drafts, and handle email attachments directly through the Gmail API.
Summary generated from the project's README
About gmail-agent MCP server
Managing email communications and file attachments through an AI agent is what gmail-agent enables. This tool provides a way for developers to connect LLM clients like Claude Desktop, Claude Code, or Cursor directly to their Gmail account using the Gmail API. It operates locally on your machine via a CLI or an MCP server over stdio, ensuring your data stays private by using your own Google Cloud OAuth client rather than a third-party server.
Users can perform a wide range of tasks including searching messages with Gmail syntax, reading threads as plain text, and managing drafts. A standout feature is its advanced handling of attachments; it can download files to your local disk without overwriting existing ones and can even extract text from PDF or text attachments without saving them. The server respects your specific Google OAuth permissions, meaning the available tools automatically match your granted access level, whether that is read-only or full modification rights.
What you can do with it
- 1Automated invoice retrievalFind and download specific financial documents from recent emails to your local machine.
- 2Email thread managementDraft, send, or reply to email threads while maintaining proper threading headers.
- 3Attachment content extractionRead the contents of PDF attachments directly within the AI context without needing to save them to disk first.
- 4Safe email draftingReview the exact content and MIME structure of an email before it is actually sent.
Written from the project's README. Every use case is checked against a quote from it.
How to install gmail-agent MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall gmail-agent MCP in Claude Code
$ claude mcp add gmail-agent -- uvx gmail-agentInstall gmail-agent MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"gmail-agent": {
"command": "uvx",
"args": [
"gmail-agent"
]
}
}
}Install gmail-agent MCP in VS Code
.vscode/mcp.json
{
"servers": {
"gmail-agent": {
"type": "stdio",
"command": "uvx",
"args": [
"gmail-agent"
]
}
}
}Install gmail-agent MCP in VS Code CLI
$ code --add-mcp '{"name":"gmail-agent","type":"stdio","command":"uvx","args":["gmail-agent"]}'Install gmail-agent MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"gmail-agent": {
"command": "uvx",
"args": [
"gmail-agent"
]
}
}
}Install gmail-agent MCP in Codex
$ codex mcp add gmail-agent -- uvx gmail-agentInstall gmail-agent MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.gmail-agent] command = "uvx" args = ["gmail-agent"]
Install gmail-agent MCP in Gemini CLI
$ gemini mcp add -s user gmail-agent uvx -- gmail-agentInstall gmail-agent MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"gmail-agent": {
"command": "uvx",
"args": [
"gmail-agent"
]
}
}
}Configuration
GMAIL_AGENT_ALLOWED_DIRSExtra folders, besides ~/Downloads, the tools may save attachments to and attach files from (separated by :)
GMAIL_AGENT_CONFIG_DIRConfig dir with credentials.json and token (default ~/.config/gmail-agent)
| Name | Description | |
|---|---|---|
| GMAIL_AGENT_ALLOWED_DIRS | Extra folders, besides ~/Downloads, the tools may save attachments to and attach files from (separated by :) | |
| GMAIL_AGENT_CONFIG_DIR | Config dir with credentials.json and token (default ~/.config/gmail-agent) |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledremok/gmail-agent is public and reachablegithub.com/dremok/gmail-agent ↗Pass
- Package names this repository as its sourcegmail-agent names dremok/gmail-agent as sourcepypi.org/project/gmail-agent/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for gmail-agentpypi.org/project/gmail-agent/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-11github.com/dremok/gmail-agent ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from gmail-agentPass
- No critical advisory in the package or its dependencies49 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubgmail-agent
Gmail for AI agents and the people who run them: search, read, download attachments, send, reply, forward, drafts, labels and trash.
gmail-agent is one small Python package with two faces:
- a CLI for agents that have a shell (Claude Code, Codex, Aider, your own scripts), with
--jsonoutput - an MCP server over stdio for clients like Claude Desktop and Claude Code
It talks directly to the Gmail API from your machine using your own Google Cloud OAuth client, so there is no third-party server in between. You choose how much access it gets when you log in, from read-only up to full.
Why another one? A lot of real agent work with mail is about attachments: find last quarter's invoices, save them, read the PDFs. The hosted Gmail connectors can't save files to disk, and the most used open-source Gmail MCP server is archived. gmail-agent handles attachments well, shows you any write before it happens, and only offers the tools your login allows. See How it compares.
What it does
Read
- Search with Gmail syntax (
from:,has:attachment,filename:pdf,newer_than:30d, ...), paginated - Read a message or a whole thread as plain text (HTML mail is converted)
- List labels and drafts
Attachments
- List a message's attachments with name, type, size and part id
- Download from one message, or every attachment from every message matching a query
- Extract text from PDF and text attachments without saving them
Downloads never overwrite anything. If invoice.pdf exists, the next one becomes invoice_1.pdf, and you get the real paths back. Names are sanitized, so a file called ../../.ssh/config lands as config inside the folder you picked.
Write
- Send new mail with attachments, Cc/Bcc, plain text or HTML
- Reply and reply-all in the same thread (In-Reply-To, References and thread id are set, the original is quoted)
- Forward, including the original attachments
- Drafts: create, list, show, update, send, delete
- Labels: create, rename, delete, add to and remove from messages or threads
- Mark read or unread, star, archive
- Trash and untrash; permanent delete behind an explicit flag
Every write command takes --dry-run, which prints the exact API request and, for mail, the MIME message without changing anything. With --json, results include the ids of whatever was sent or created.
Quick start
You need uv (or pipx) and Python 3.11+.
uv tool install gmail-agent # or: pipx install gmail-agent
For the latest unreleased changes: uv tool install git+https://github.com/dremok/gmail-agent.
Then set it up once (about 5 minutes, guided):
gmail-agent setup # Google Cloud project, OAuth client and login; default access level is "modify"
gmail-agent status # shows the logged-in account and access level
gmail-agent search "has:attachment newer_than:7d"
Then connect your agent. In Claude Code: /plugin install gmail-agent --marketplace dremok/gmail-agent. For Codex, Gemini CLI, VS Code, Cursor and Claude Desktop, see MCP server.
How it compares
Checked against each project's source and docs in October 2026. Corrections are welcome as issues.
| gmail-agent | Claude's Gmail connector | google_workspace_mcp | GongRzhe Gmail-MCP-Server | |
|---|---|---|---|---|
| Setup | Your own OAuth client; gmail-agent setup guides you (about 5 minutes) |
One click | Your own OAuth client, by hand | Your own OAuth client, by hand |
| Runs as | CLI and stdio MCP, on your machine | Hosted (web, desktop, mobile) | stdio or HTTP, multi-user | stdio MCP |
| Save attachments to disk | Yes, never overwrites | No | Yes, to its own folder, deleted after an hour | Yes, overwrites files with the same name |
| Every attachment matching a search | Yes | No | No | No |
| Text of PDF attachments | Yes | No | No | No |
| Forward with original attachments | Yes | Not documented | Yes | No forward |
| Drafts | Create, update, send, delete | Yes | Create only | Create only |
| Dry run of every write, with the MIME message | Yes | No, asks before each write instead | No | No |
| Read-only mode | Yes | No, the grant includes sending | Yes | No |
| Tool list follows the granted scope | Yes | No | From server flags | No |
| Permanent delete | Only with --allow-delete and a full login |
Not offered | Not offered | Offered without a guard |
| Drive, Calendar, Docs | No, Gmail only | Separate connectors | Yes | No |
| Maintained | Yes | Yes | Yes | Archived in 2025 |
Use something else if:
- You want no setup, or use Claude on the web or your phone. The built-in connector is one click away.
- You need Drive, Calendar and Docs in the same server, or one server for a team over HTTP. google_workspace_mcp covers all of Workspace.
- You need Gmail filters, sending from an alias, your Gmail signature or inline images in outgoing mail. gmail-agent does none of these yet.
- You want a plain CLI for all of Google Workspace. googleworkspace/cli (
gws) is a good one. It dropped its MCP server in version 0.8.0.
Coming from GongRzhe/Gmail-MCP-Server?
That server is archived. Moving takes a few minutes, and you can keep your Google Cloud project.
-
Install:
uv tool install gmail-agent -
Reuse your OAuth client, not your token. Setup checks the client, installs it and logs you in:
gmail-agent setup --client-file ~/.gmail-mcp/gcp-oauth.keys.jsonDo not copy GongRzhe's
credentials.jsonby hand. Despite the name it is your login token, while gmail-agent'scredentials.jsonis the OAuth client, and the token formats differ anyway. gmail-agent needs a Desktop app client. If yours is a Web application client, setup says so; create a Desktop client in the same project and pass that file instead. -
Point your MCP client at gmail-agent. Replace
npx @gongrzhe/server-gmail-autoauth-mcpwithgmail-agent mcp, for exampleclaude mcp add gmail --scope user -- gmail-agent mcp. For Claude Desktop, see MCP server. -
Optional cleanup: revoke the old grant at myaccount.google.com/permissions and remove
~/.gmail-mcp.
| GongRzhe tool | gmail-agent tool | Notes |
|---|---|---|
search_emails |
search_messages |
Adds paging with page_token |
read_email |
get_message, get_thread |
HTML mail comes back as text |
send_email |
send_message, reply_to_message |
Replies set the threading headers for you |
draft_email |
create_draft, or any send tool with as_draft |
Drafts can also be updated and sent |
modify_email, batch_modify_emails |
modify_labels, mark_messages |
Labels by name or id |
delete_email, batch_delete_emails |
trash |
Permanent delete needs mcp --allow-delete and a full login |
list_email_labels |
list_labels |
|
create_label, update_label, delete_label |
create_label, rename_label, delete_label |
No visibility options |
get_or_create_label |
list_labels, then create_label |
|
download_attachment |
download_attachments |
Picks by filename or part id, never overwrites |
download_matching_attachments, read_attachment_text, forward_message |
New | |
create_filter and the other filter tools |
None | gmail-agent never touches settings, filters or forwarding |
Two behaviours differ on purpose: delete means trash unless you opt in, and the tool list shrinks to what your login allows. If tools seem to be missing, check the level with gmail-agent status.
Google Cloud setup
Gmail has no API keys for personal mail, so you create your own OAuth client in Google Cloud. It is free and you do it once. gmail-agent setup walks you through it and does what Google lets it do for you:
- Project and Gmail API. If gcloud is installed and logged in, setup creates a project called
gmail-agent-plus six random characters (it asks first) and enables the Gmail API. Without gcloud it opens the two console pages and asks for the project ID.--project IDuses a project you already have. - Consent screen and publishing. Google has no API for these, so setup opens the pages and tells you what to click: app name
gmail-agent, audience External, then Publish app so the status is In production. Publishing avoids the 7-day login expiry of Testing mode, and you do not have to add yourself as a test user. Google calls the app unverified, which is expected for your own app and fine for personal use (it is capped at 100 users). - Desktop client. Setup opens the Clients page. Create a client of type Desktop app and click Download JSON (Google shows the secret only then). Setup spots the file in
~/Downloads, checks that it is a Desktop client from the right project, and installs it as~/.config/gmail-agent/credentials.json, readable only by you. You can also pass--client-file PATH, or press Ctrl-C and paste the client ID and secret. - Login. A browser opens; pick your account. Google says "Google hasn't verified this app": click Continue and keep all boxes ticked. Setup checks the account and prints
Set up: logged in as you@example.com with modify access.
Run it again whenever you like; it skips what is already done. Options: --scope LEVEL (see Access levels), --no-gcloud, and --no-browser, which prints the links instead of opening them (the login redirect goes to localhost, so the browser must run on the same machine).
Setting up by hand
The same steps without the wizard:
-
Create a project at console.cloud.google.com/projectcreate and make sure it is selected in the top bar.
-
Enable the Gmail API on the Gmail API page.
-
Configure the consent screen in Google Auth Platform: Get started, app name
gmail-agent, your address as support and contact email, audience External, agree, Create. -
Publish the app under Audience (Publish app, status In production). If you would rather stay in Testing mode, add your address under Test users instead, and expect to log in again every 7 days.
-
Create a Desktop client under Clients: Create client, application type Desktop app, Create, and download the JSON from the dialog. If you miss the download, create a new client.
-
Install it, either with
gmail-agent setup --client-file ~/Downloads/client_secret_*.json, which also logs in, or by hand:mkdir -p ~/.config/gmail-agent mv ~/Downloads/client_secret_*.json ~/.config/gmail-agent/credentials.json chmod 600 ~/.config/gmail-agent/credentials.json gmail-agent login # or: gmail-agent login --scope readonly
If something is missing later, the error names the fix: a deleted or expired client points back to gmail-agent setup, a Gmail API that is not enabled comes with the link to enable it, and an expired login says to run gmail-agent login (and to publish the app if it happens every 7 days).
Access levels
Pick one with gmail-agent login --scope LEVEL. To change it later, run login again.
| Level | Google scope | What a token with it can do |
|---|---|---|
readonly |
gmail.readonly |
Read all mail, labels and settings. Cannot change anything. |
compose |
gmail.readonly + gmail.compose |
Read, plus create, change and delete drafts, and send mail. |
modify (default) |
gmail.modify |
Everything except permanent deletion: read, send, drafts, labels, archive, trash. |
full |
https://mail.google.com/ |
Everything, including deleting mail permanently. Also grants IMAP/SMTP-level access. |
If a command needs more than your login has, it stops before calling Gmail and tells you exactly what to run, for example:
error: Sending needs send/draft access, but this login only granted gmail.readonly. Run: gmail-agent login --scope compose
Only use full if you want permanent delete. Trash (available with modify) is emptied by Gmail after 30 days anyway.
CLI usage
Every command takes --json for machine-readable output, before or after the command (gmail-agent --json search ... and gmail-agent search ... --json both work). Run gmail-agent <command> --help for all options.
Read and download
gmail-agent search "from:billing@example.com newer_than:30d"
gmail-agent search "has:attachment filename:pdf" -n 50 --json
gmail-agent search "label:receipts" --page-token <token from the previous page>
gmail-agent message 18c2f0a1b2c3d4e5
gmail-agent thread 18c2f0a1b2c3d4e5
gmail-agent labels
gmail-agent attachments 18c2f0a1b2c3d4e5
gmail-agent download 18c2f0a1b2c3d4e5 -o ~/Downloads/mail # all of them
gmail-agent download 18c2f0a1b2c3d4e5 -o ./out --name invoice.pdf # by filename
gmail-agent download 18c2f0a1b2c3d4e5 -o ./out --name 1.2 # by part id
gmail-agent fetch "subject:invoice after:2026/01/01" -o ./invoices --match "*.pdf"
gmail-agent read 18c2f0a1b2c3d4e5 invoice.pdf # print PDF text
Send, reply, forward
gmail-agent send --to alice@example.com --cc bob@example.com --subject "Report" \
--body "Attached." --attach report.pdf
gmail-agent send --to alice@example.com --subject "News" --html-file news.html
gmail-agent reply 18c2f0a1b2c3d4e5 --body "Thanks, got it."
gmail-agent reply 18c2f0a1b2c3d4e5 --all --body-file answer.txt --no-quote
gmail-agent forward 18c2f0a1b2c3d4e5 --to carol@example.com --body "FYI"
gmail-agent forward 18c2f0a1b2c3d4e5 --to carol@example.com --no-attachments --draft
send, reply and forward send right away. Add --draft to save to Drafts instead, or --dry-run to see what would go out. With --html and no --body, a plain-text version is derived from the HTML. Forwards leave out images that were embedded in the original HTML (logos, signatures); real attachments go along.
Drafts
gmail-agent draft list
gmail-agent draft create --to alice@example.com --subject "Plan" --body "First version"
gmail-agent draft get r-123456789
gmail-agent draft update r-123456789 --body "Second version" --attach notes.pdf
gmail-agent draft send r-123456789
gmail-agent draft delete r-123456789
draft update keeps every field you do not pass, including attachments (use --drop-attachments to clear them) and the thread of a draft reply.
Labels and state
gmail-agent label create "Receipts/2026"
gmail-agent label rename "Receipts/2026" "Receipts/Tax 2026"
gmail-agent label add Receipts 18c2f0a1b2c3d4e5 18c2f0a1b2c3d4e6
gmail-agent label remove Receipts 18c2f0a1b2c3d4e5
gmail-agent label delete "Receipts/Tax 2026"
gmail-agent mark-read 18c2f0a1b2c3d4e5
gmail-agent star 18c2f0a1b2c3d4e5
gmail-agent archive 18c2f0a1b2c3d4e5 --thread # ids are thread ids
gmail-agent trash 18c2f0a1b2c3d4e5
gmail-agent untrash 18c2f0a1b2c3d4e5
gmail-agent delete 18c2f0a1b2c3d4e5 --permanent # needs login --scope full
Labels can be given by name (case-insensitive) or id. The state commands also exist as mark-unread, unstar and unarchive. delete refuses to run without --permanent.
Dry run
$ gmail-agent trash 18c2f0a1b2c3d4e5 --dry-run
Dry run, nothing was changed.
{
"method": "users.messages.trash",
"params": {
"id": "18c2f0a1b2c3d4e5"
}
}
For mail, the dry run also prints the MIME message: every header and body part, with each attachment's contents replaced by its size.
Exit codes: 0 ok, 1 error, 2 a setup step or scope is missing (the message says which).
MCP server
gmail-agent mcp runs an MCP server over stdio. It starts even before you log in; tools then return an error telling the user to run gmail-agent login.
Claude Code plugin (recommended for Claude Code). It adds the MCP server plus a skill that tells Claude when and how to use it: attachments, dry runs before sending, and treating mail as untrusted.
/plugin install gmail-agent --marketplace dremok/gmail-agent
On Claude Code older than 2.1.275, run /plugin marketplace add dremok/gmail-agent, then /plugin install gmail-agent@dremok. The plugin runs the server with uvx, so you need uv. If you also added the server with claude mcp add, remove that entry (claude mcp remove gmail) or you get every tool twice.
Claude Code without the plugin (--scope user here is Claude Code's config scope, not the Gmail access level):
claude mcp add gmail --scope user -- gmail-agent mcp
claude mcp add gmail --scope user -- gmail-agent mcp --read-only # reading tools only
claude mcp add gmail --scope user -- uvx gmail-agent mcp # without installing first
Codex, Gemini CLI and VS Code:
codex mcp add gmail -- uvx gmail-agent mcp
gemini mcp add --scope user gmail uvx gmail-agent mcp
code --add-mcp '{"name":"gmail","command":"uvx","args":["gmail-agent","mcp"]}'
Cursor, Windsurf, Cline and other clients take the usual JSON (for Cursor, in ~/.cursor/mcp.json):
{
"mcpServers": {
"gmail": { "command": "uvx", "args": ["gmail-agent", "mcp"] }
}
}
Claude Desktop: edit claude_desktop_config.json (Settings > Developer > Edit Config). Desktop apps often do not see your shell's PATH, so use the absolute path from which gmail-agent:
{
"mcpServers": {
"gmail": {
"command": "/Users/you/.local/bin/gmail-agent",
"args": ["mcp"]
}
}
}
Without installing first, uvx works too (again with its absolute path, from which uvx): "command": "/Users/you/.local/bin/uvx", "args": ["gmail-agent", "mcp"].
Which tools show up follows the access level in your saved login: readonly gets only the reading tools, compose adds sending and drafts, modify adds labels, state and trash. Before you have logged in, the server offers the modify set, and each tool explains how to log in. After changing the level with gmail-agent login --scope ..., restart the MCP client so it picks up the new tool list.
Server flags: --read-only keeps only the reading tools, whatever the login allows. --allow-delete adds delete_permanently, and only if the login has full access. Without both, the server has no way to delete mail permanently. --allow-dir PATH (repeatable) lets the tools save attachments to and attach files from another folder besides ~/Downloads; see Local files.
For example, to let Claude Code save attachments in a project folder too:
claude mcp add gmail --scope user -- gmail-agent mcp --allow-dir ~/code/my-project
Tools:
| Tool | What it does |
|---|---|
account_status |
Logged-in address, message counts, access level |
search_messages |
Gmail query, paginated; id, thread, date, from, subject, snippet, attachments |
get_message, get_thread |
Headers, plain-text body, attachment list |
list_labels |
System and user labels |
list_attachments |
Attachments of a message with part ids |
download_attachments |
Save all or selected attachments of a message to a folder |
download_matching_attachments |
Save attachments from every message matching a query |
read_attachment_text |
Text of a PDF or text attachment, without saving |
list_drafts, get_draft |
Drafts and their content |
send_message, reply_to_message, forward_message |
Send now, or with as_draft save to Drafts |
create_draft, update_draft, send_draft, delete_draft |
Draft management |
create_label, rename_label, delete_label |
Label management |
modify_labels, mark_messages |
Add/remove labels; read, unread, star, unstar, archive, unarchive |
trash, untrash |
Move to and from Trash |
delete_permanently |
Only with --allow-delete and a full login |
Every write tool takes dry_run. Every tool carries all four MCP hints. Reading tools are readOnlyHint. Sending (send_message, reply_to_message, forward_message, send_draft), update_draft, trash and the delete tools are destructiveHint, because they cannot be taken back or they overwrite or remove something, so clients that confirm destructive calls will ask first. Tools that are safe to repeat, such as mark_messages and trash, are idempotentHint; send_message and the downloads are not.
gmail-agent MCP questions
How do I add gmail-agent MCP to Claude Code?
Run claude mcp add gmail-agent -- uvx gmail-agent in your terminal. Add --scope user to make it available in every project.
How do I add gmail-agent MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can this server save attachments to my local disk?
Yes, it can download attachments from specific messages or all messages matching a query, and it ensures files are never overwritten by renaming duplicates.
How does it handle security and privacy?
It uses your own Google Cloud OAuth client to talk directly to the Gmail API from your machine, meaning there is no third-party server involved.
Can I test write operations before they happen?
Yes, every write command supports a dry-run mode that prints the exact API request and the MIME message without making changes.