Skip to content
MCP server

Gmail Tidy MCP

Tidy several Gmail accounts from an assistant, with no way to send or delete mail

Runs locallyStatus and history
Install
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-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "gmail-tidy-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "gmail-tidy-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "gmail-tidy-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "gmail-tidy-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

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.

How AIPoweredBot checks servers