Gmail Tidy MCP
Tidy several Gmail accounts from an assistant, with no way to send or delete mail
- Pricing
- Open source
- Platforms
- CLI, macOS, Windows
- Runs
- Locally
- Version
- 0.5.1
- Listing updated
- today
Similar MCP servers
About Gmail Tidy MCP
Gmail Tidy MCP is an open-source MCP server for communication. It runs locally on your machine and is started by your AI client.
This server is built around a deliberate limit: there is no tool for sending, replying, forwarding or deleting email, and a test fails the build if such a call ever appears in the code. Within that limit an assistant can search across multiple Gmail accounts at once, read threads, label and archive in bulk (up to 5,000 messages per call), create filters, and write drafts that you send yourself from Gmail.
A few tools go beyond housekeeping. sender_stats shows who writes most, newsletters lists mailing lists by volume with each declared unsubscribe link but never unsubscribes, and get_attachment reads text, gz and zip files inline, such as DMARC reports. Other files are saved to a downloads folder, and risky ones like executables or disguised names are refused unless overridden.
The README spends most of its length on safety. Tokens are encrypted with AES-256-GCM using a key from the OS keychain, you bring your own OAuth client, and email content is fenced off as untrusted with invisible characters stripped. It also adds notes for prompt-injection phrasing, failed SPF, DKIM or DMARC and lookalike senders, and logs every change locally so a session can be reviewed. The README admits the Gmail scope it must request technically allows sending, so the guarantee comes from the code, and it lists what a manipulated model could still do.
Install
Run in a terminal
claude mcp add gmail-tidy-mcp -- npx -y gmail-tidy-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"gmail-tidy-mcp": {
"command": "npx",
"args": [
"-y",
"gmail-tidy-mcp"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"gmail-tidy-mcp": {
"command": "npx",
"args": [
"-y",
"gmail-tidy-mcp"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"gmail-tidy-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"gmail-tidy-mcp"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"gmail-tidy-mcp": {
"command": "npx",
"args": [
"-y",
"gmail-tidy-mcp"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"gmail-tidy-mcp": {
"command": "npx",
"args": [
"-y",
"gmail-tidy-mcp"
]
}
}
}Using several servers? Build one config file with the MCP config generator.
Tools this server provides (23)
Taken from the project documentation; the running server may differ.
- list_accounts
- List connected accounts.
- check_accounts
- Check account connections.
- connect_account
- Start connecting an account.
- finish_connect_account
- Finish connecting an account.
- search_emails
- Search mail with Gmail syntax.
- search_all_accounts
- Search every account at once.
- get_email
- Read an email and list attachments.
- get_thread
- Read a whole conversation.
- get_attachment
- Read or save an attachment.
- sender_stats
- Who writes most, by address and domain.
- newsletters
- Mailing lists by volume with unsubscribe links.
- list_labels
- List labels.
- create_label
- Create a label.
- update_label
- Rename or recolor a label.
- organize_emails
- Add or remove labels in bulk.
- list_filters
- List filters.
- create_filter
- Create a filter.
- delete_filter
- Delete a filter.
- create_draft
- Create a draft.
- list_drafts
- List drafts.
- update_draft
- Edit an existing draft.
- set_signature
- Change the signature.
- recent_changes
- Review changes this server made.
What it does
- No send or delete
- The tools cannot send, reply, forward, delete or move mail to Trash or Spam.
- Multi-account search
- One search can span every connected Gmail account.
- Bulk organizing
- Add or remove labels, archive or mark read up to 5,000 messages at a time.
- Filters and drafts
- Create filters and drafts, including replies with local attachments.
- Prompt-injection guards
- Email content is fenced as untrusted and flagged for common tricks.
- Audit log
- recent_changes lists every change the server made.
Good for
- Archive old newsletters in a work account
- List which senders fill an inbox
- Review DMARC reports from attachments
- Set up labels and filters for a new mailbox
- Prepare reply drafts to check and send yourself
Pricing
Open source
Free, runs locally
More servers for the same service
Gmail Tidy MCP FAQ
Can it send email?
No. There is no send or delete tool, and a test enforces that.
Where are tokens stored?
Encrypted with AES-256-GCM in a local file, with the key in the macOS Keychain, Linux Secret Service or a DPAPI-protected file on Windows.
Do I need my own Google credentials?
Yes, it uses your own OAuth client with no shared client or third-party server.
Can it undo changes?
The audit log from recent_changes shows what changed so labels, archiving and drafts can be reviewed and reversed.
Is Gmail Tidy MCP free?
Yes. Gmail Tidy MCP is open source, so you can use and self-host it for free.
How do I add Gmail Tidy MCP to Claude Code?
Run this command in your terminal: claude mcp add gmail-tidy-mcp -- npx -y gmail-tidy-mcp
What are the best alternatives to Gmail Tidy MCP?
The closest alternatives to Gmail Tidy MCP are TrendRadar, Ha MCP, Concord MCP, Getmitra and note1.
Where this comes from
- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

