Skip to content
MCP server

mcp-mail

Self-hosted IMAP/SMTP email for any MCP client, with per-client permissions

Runs locallyStatus and history
Pricing
Open source
Platforms
self-hosted, CLI, Linux
Runs
Locally
Version
1.2.1
Listing updated
3 days ago

About mcp-mail

mcp-mail is an open-source MCP server for communication. It runs locally on your machine and is started by your AI client.

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.

Install

Run in a terminal

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

Add to claude_desktop_config.json

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

Add to ~/.cursor/mcp.json

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

Add to .vscode/mcp.json

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

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Configuration

  • ACCOUNTS_FILEPath to accounts.json (default ~/.config/mcp-mail/accounts.json)
  • STDIO_PRESETread-only | read-draft | organize | full-no-delete | full

Tools this server provides (14)

Taken from the project documentation; the running server may differ.

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.

What it does

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

Pricing

Open source

Prices change. Check annseraf.github.io before you buy.

mcp-mail 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 to mcp-mail

  1. Ha MCP

    MCP server

    MCP server for managing and automating Home Assistant from AI assistants

    Runs locally
    • 8 tools
    • Open source
    • 7.9K GitHub stars
    • Productivity
  2. Concord MCP

    MCP server

    Local-first MCP server for messaging and shared work-state between coding agents

    Runs locally
    • Freemium
    • 1.3K GitHub stars
    • Developer tools
  3. note1

    MCP server

    MCP server giving AI assistants search and summaries across your note1 meetings

    • 4 tools
    • Remote
    • Free trial
    • 1 GitHub star
    • Productivity
  4. BoardAgent

    MCP server

    Remote MCP server for a message board where only AI agents post, reply and vote

    • 27 tools
    • Remote
    • Free
    • Community directories
  5. Callout

    MCP server

    Let an AI agent place real phone calls in Japanese or English and read the transcript

    • 5 tools
    • Remote
    • Freemium
    • Communication
  6. CalderFlow

    MCP server

    Turn notes or specs into editable flowcharts, timelines and funnels from an AI assistant

    • 10 tools
    • Remote
    • Free
    • Design and media