Which integrations are available for this server?

Provides tools to read, search, send, label, and manage Gmail emails through OAuth2, including batch operations and file-export for large result sets.

How do I use gmail-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gmail-mcp List my 5 most recent unread emails" 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

by DimitrisPasakaleris

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Gmail MCP

Python 3.11+ License: MIT MCP

An MCP server that lets Claude (Desktop, Code, or any MCP client) read, search, send, label, and manage your Gmail through OAuth2. 25 tools, batch operations, file-export for large result sets, retry-with-backoff, and OS-keyring token storage.

Highlights

25 tools across single, batch, and file-export families — see docs/TOOLS.md.
Batch operations that bundle up to 100 Gmail calls per MCP request (read_emails, add_labels, archive_emails, …) for fast bulk workflows.
File-export tools (read_emails_full, search_and_save, append_emails) save results to .md / .json / .jsonl / .csv so MCP output limits aren't hit when working with hundreds of emails.
Resilient: exponential-backoff retry on 429/503, respects Retry-After, recovers from transient network failures.
Secure token storage via OS keyring (optional) or filesystem (default).
Tested: ~700 lines of unit tests, mocked Google client, no network in CI.

Related MCP server: Gmail MCP Server

Quick start

pip install -e .                      # install in editable mode
# (or once published: pipx install gmail-mcp)

Then:

Get a credentials.json from Google Cloud Console — see docs/google-cloud-setup.md.
Place it at the OS config dir (~/.config/gmail-mcp/credentials.json on Linux/macOS, %APPDATA%\gmail-mcp\credentials.json on Windows).
Run gmail-mcp once in a terminal — it opens a browser for the OAuth flow and caches the token.

mcp install src/gmail_mcp/server.py --name gmail-mcp

Or, if you installed via pip, the gmail-mcp console script works too:

mcp install $(which gmail-mcp) --name gmail-mcp

Restart Claude Desktop. Try: "List my 5 most recent unread emails."

Configuration

Set environment variables (or edit src/gmail_mcp/config.py):

Variable	Default	Effect
`GMAIL_MCP_CONFIG_DIR`	OS-specific (see below)	Overrides where `credentials.json`, `token.json`, and `gmail-mcp.log` live.

OS-specific config dir defaults:

Linux: ~/.config/gmail-mcp/
macOS: ~/Library/Application Support/gmail-mcp/
Windows: %APPDATA%\gmail-mcp\

To switch to OS keyring storage, set Config.token_storage = "keyring" in config.py and delete the cached token.json so the OAuth flow re-runs.

Tools at a glance

Family	Tools
Single	`list_emails`, `get_thread_messages`, `read_email`, `send_email`, `reply_email`, `archive_email`, `trash_email`, `mark_read`, `add_label`, `remove_label`, `create_draft`, `list_drafts`, `update_draft`, `delete_draft`, `list_attachments`, `download_attachment`
Batch	`read_emails`, `mark_emails_read`, `archive_emails`, `trash_emails`, `add_labels`, `download_attachments`
File export	`read_emails_full`, `search_and_save`, `append_emails`

Full parameter reference and examples: docs/TOOLS.md.

Documentation

docs/google-cloud-setup.md — step-by-step OAuth client setup.
docs/ARCHITECTURE.md — module map, request flow, design decisions.
docs/TROUBLESHOOTING.md — common errors and fixes.
docs/TOOLS.md — every tool, every parameter, every response.

Contributing

See CONTRIBUTING.md for dev setup, tests, and the PR checklist. Bug reports and feature requests welcome via GitHub Issues.

License

MIT.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

gmail AOAuth
com.mintmcp
A MCP server for Gmail that lets you search, read, and draft emails and replies.
Communication App Automation Workplace & Productivity
124
email A
dev.primitive
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email Communication
302
Remote Desktop CommanderOAuth
app.desktopcommander
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Shell Access OS Automation
265
ClawLinkOAuth
dev.claw-link
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
App Automation Workplace & Productivity
24

Related MCP Servers

mcp-gmail
Email App Automation
knowledgeislands
A
license
B
quality
F
maintenance
MCP server that connects Claude with Gmail to read, send, delete, and manage messages and labels via the Google Gmail API.
Updated 2 months ago (2026-07-08 22:58 UTC)
3
MIT
Gmail MCP Server
Email Communication
stevesimpson418
A
license
Not graded
quality
C
maintenance
A local MCP server that provides tool-level access to Gmail, allowing Claude to search, read, send, and manage emails using the Gmail API.
Updated 2 months ago (2026-07-28 04:08 UTC)
1
MIT
claude-gmail-mcp
Email Communication Search
pliablepixels
A
license
A
quality
D
maintenance
A Gmail MCP server that enables Claude to send, search, and read emails using either Gmail API or SMTP/IMAP backend.
Updated 5 months ago (2026-04-18 14:05 UTC)
3
43 PyPI
MIT
Gmail MCP Server
Email App Automation
Paviyarasanmani
A
license
Not graded
quality
D
maintenance
A custom MCP server that gives Claude full Gmail control — send directly, read, reply, search, label, and delete emails.
Updated 3 months ago (2026-06-19 06:01 UTC)
98 npm
MIT