# mcp-mail

> mcp-mail is an open-source MCP server for communication. Self-hosted IMAP/SMTP email for any MCP client, with per-client permissions. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** self-hosted, CLI, Linux, macOS
- **Website:** https://annseraf.github.io/mcp-mail/
- **Repository:** https://github.com/annseraf/mcp-mail
- **MCP Registry name:** io.github.Annseraf/mcp-mail
- **Categories:** communication, productivity
- **Listing updated:** 2026-11-14

## About

Permissions are the focus here. Each client connects with a capability level and the stdio preset can be read-only, read-draft, organize, full-no-delete or full, so an assistant that only needs to read mail cannot send or delete. The tool table tags every tool as read, draft, organize or destructive, and every action is written to an audit log. Deleting moves a message to Trash unless `permanent: true` is passed.

It works with any IMAP/SMTP mailbox, including Fastmail, iCloud, Gmail and Google Workspace with an app password, Yahoo, Zoho and Dovecot or Postfix servers, and optionally any CalDAV calendar. Beyond reading and sending, it can search across all folders, read a whole thread across Inbox and Sent, save drafts with attachments and fetch size-capped attachments.

The README describes it as a maintained continuation of claude-mail-mcp by Markus Stöger, and existing v0.2 installs can switch without config changes. A one-line installer sets up a server for URL-based clients such as Claude.ai and ChatGPT, while local clients can run `npx -y @annseraf/mcp-mail stdio`.

## Features

- **Permission presets:** Choose read-only, read-draft, organize, full-no-delete or full.
- **Audit log:** Records what each connected client did.
- **Any mailbox:** Connects to any IMAP/SMTP provider, not just one vendor.
- **Thread reading:** Reads a full conversation across Inbox and Sent.
- **Drafts with attachments:** Saves drafts and fills in replies from a message uid.
- **Optional calendars:** Supports any CalDAV server alongside mail.

## Good for

- Let an assistant triage an inbox without sending anything
- Search every folder for a sender or subject
- Draft replies for review before sending
- Give different MCP clients different mail permissions
- Read a long thread and summarize it

## Install

### Claude Code (Terminal)

```sh
claude mcp add mcp-mail -- npx -y @annseraf/mcp-mail
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "mcp-mail": {
      "command": "npx",
      "args": [
        "-y",
        "@annseraf/mcp-mail"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "mcp-mail": {
      "command": "npx",
      "args": [
        "-y",
        "@annseraf/mcp-mail"
      ]
    }
  }
}
```

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

```json
{
  "servers": {
    "mcp-mail": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@annseraf/mcp-mail"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "mcp-mail": {
      "command": "npx",
      "args": [
        "-y",
        "@annseraf/mcp-mail"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "mcp-mail": {
      "command": "npx",
      "args": [
        "-y",
        "@annseraf/mcp-mail"
      ]
    }
  }
}
```

## Tools

- `list_accounts`: Lists connected mailboxes, sender names and signatures, never credentials.
- `list_folders`: Lists folders with their special use.
- `list_messages`: Newest messages in a folder with short previews.
- `search_messages`: Searches one, several or all folders by sender, subject, body, date or flags.
- `get_message`: Reads one message with headers, body and attachment list.
- `get_attachment`: Downloads one size-capped attachment.
- `get_thread`: Reads a whole conversation across Inbox and Sent.
- `list_threads`: Groups a folder's newest messages into conversations.
- `create_draft`: Saves a draft, optionally filling in a reply.
- `mark_read`: Marks a message read or unread.
- `set_flags`: Stars, marks answered or adds custom keywords.
- `move_message`: Moves a message to another folder.
- `delete_message`: Moves to Trash, or deletes permanently on request.
- `send_message`: Sends an email.

## FAQ

### Can I stop an assistant from sending or deleting mail?

Yes. Pick a preset such as read-only or full-no-delete, or set permissions per client.

### Which mail providers work?

Any IMAP/SMTP mailbox, including Fastmail, iCloud, Gmail with an app password, Yahoo and Zoho.

### Does delete remove mail permanently?

Not by default; `delete_message` moves to Trash unless `permanent: true` is set.

### Which AI clients are supported?

Claude.ai, Claude Desktop, Claude Code, ChatGPT, Cursor, VS Code, Meta Muse and any MCP client.

### Is mcp-mail free?

Yes. mcp-mail is open source, so you can use and self-host it for free.

### How do I add mcp-mail to Claude Code?

Run this command in your terminal: claude mcp add mcp-mail -- npx -y @annseraf/mcp-mail

### What are the best alternatives to mcp-mail?

The closest alternatives to mcp-mail are Ha MCP, Concord MCP, note1, BoardAgent and Callout.

## Alternatives

- [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.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [BoardAgent](https://ai-powered.com/mcp/boardagent): BoardAgent is a free MCP server for community directories.
- [Callout](https://ai-powered.com/mcp/callout): Callout is a freemium MCP server for communication.
- [CalderFlow](https://ai-powered.com/mcp/calderflow): CalderFlow is a free MCP server for design and media.
- [nicemails](https://ai-powered.com/mcp/nicemails): nicemails is a freemium MCP server for communication.
- [SOMMON Office](https://ai-powered.com/mcp/sommon-office): SOMMON Office is a paid MCP server for communication.

---
Source: https://ai-powered.com/mcp/mcp-mail
