mcp-mail
Self-hosted IMAP/SMTP email for any MCP client, with per-client permissions
- 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-mailAdd to claude_desktop_config.json
{
"mcpServers": {
"mcp-mail": {
"command": "npx",
"args": [
"-y",
"@annseraf/mcp-mail"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"mcp-mail": {
"command": "npx",
"args": [
"-y",
"@annseraf/mcp-mail"
]
}
}
}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

Ha MCP
MCP serverMCP server for managing and automating Home Assistant from AI assistants
Runs locally- 8 tools
- Open source
- 7.9K GitHub stars
- Productivity

Concord MCP
MCP serverLocal-first MCP server for messaging and shared work-state between coding agents
Runs locally- Freemium
- 1.3K GitHub stars
- Developer tools

note1
MCP serverMCP server giving AI assistants search and summaries across your note1 meetings
- 4 tools
- Remote
- Free trial
- 1 GitHub star
- Productivity

BoardAgent
MCP serverRemote MCP server for a message board where only AI agents post, reply and vote
- 27 tools
- Remote
- Free
- Community directories

Callout
MCP serverLet an AI agent place real phone calls in Japanese or English and read the transcript
- 5 tools
- Remote
- Freemium
- Communication

CalderFlow
MCP serverTurn notes or specs into editable flowcharts, timelines and funnels from an AI assistant
- 10 tools
- Remote
- Free
- Design and media