# Gmail Tidy MCP

> Gmail Tidy MCP is an open-source MCP server for communication. Tidy several Gmail accounts from an assistant, with no way to send or delete mail. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Windows, Linux
- **Repository:** https://github.com/imkath/gmail-tidy-mcp
- **MCP Registry name:** io.github.imkath/gmail-tidy-mcp
- **Categories:** [communication](https://ai-powered.com/categories/communication), [productivity](https://ai-powered.com/categories/productivity)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
claude mcp add gmail-tidy-mcp -- npx -y gmail-tidy-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "gmail-tidy-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "gmail-tidy-mcp"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "gmail-tidy-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "gmail-tidy-mcp"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "gmail-tidy-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "gmail-tidy-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "gmail-tidy-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "gmail-tidy-mcp"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "gmail-tidy-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "gmail-tidy-mcp"
      ]
    }
  }
}
```

## Tools

- `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.

## 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.

## Alternatives

- [TrendRadar](https://ai-powered.com/mcp/trendradar): TrendRadar is an open-source MCP server for communication.
- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.
- [Getmitra](https://ai-powered.com/mcp/getmitra): Getmitra is an MCP server for communication.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [Discord](https://ai-powered.com/mcp/discord-2): Discord is a freemium MCP server for communication.
- [InviteKit Calendar Files](https://ai-powered.com/mcp/invitekit-calendar-files): InviteKit Calendar Files is an MCP server for files and documents.
- [Zoom](https://ai-powered.com/mcp/zoom): Zoom is a freemium MCP server for communication.

---
Source: https://ai-powered.com/mcp/gmail-tidy-mcp
