simple-email-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@simple-email-mcp search for emails about project from last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
simple-email-mcp
A provider-agnostic MCP server for email (IMAP/SMTP). Works with any email provider — Purelymail, Gmail, Outlook, DomainFactory, or any standard IMAP/SMTP server.
Built for Claude Desktop, Claude Code, and any MCP-compatible client.
Features
Multi-account — manage multiple email accounts from different providers
Read, search, list — full IMAP support with folder browsing
Send emails — plain text, HTML, or both (multipart/alternative)
Attachments — send via file path or base64-encoded inline data
Download attachments — extract attachments from received emails as base64
Calendar invites — send proper ICS invitations with Accept/Decline buttons
Save to Sent — automatically saves sent emails to the Sent folder via IMAP
Optional send gate — configurable confirmation code to prevent accidental sends
International folders — handles UTF-7 encoded folder names (German, etc.)
Compact MCP surface — one
emailtool with lazy action discovery to reduce client context use
Related MCP server: imap-mail-mcp
Quick Start
1. Install
pip install simple-email-mcpOr from source:
git clone https://github.com/mexican75/simple-email-mcp.git
cd simple-email-mcp
pip install .2. Create accounts.json
{
"accounts": [
{
"name": "personal",
"address": "me@example.com",
"password": "your-app-password",
"provider": "gmail"
}
]
}3. Add to your client
Claude Code (global, all projects):
claude mcp add email -s user -e ACCOUNTS_FILE=/path/to/accounts.json -- simple-email-mcpClaude Desktop — add to config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"email": {
"command": "simple-email-mcp"
}
}
}Or if running from source:
{
"mcpServers": {
"email": {
"command": "python",
"args": ["/path/to/simple_email_mcp.py"]
}
}
}4. Restart your client
Configuration
accounts.json
{
"send_code": "MYSECRETCODE",
"accounts": [
{
"name": "work",
"address": "me@company.com",
"send_as": "alias@company.com",
"display_name": "Jane Doe",
"description": "Primary work mailbox",
"password": "app-password",
"provider": "outlook"
},
{
"name": "personal",
"address": "me@gmail.com",
"password": "app-password",
"provider": "gmail"
},
{
"name": "custom",
"address": "me@mydomain.com",
"password": "password",
"imap_host": "mail.mydomain.com",
"imap_port": 993,
"smtp_host": "mail.mydomain.com",
"smtp_port": 587,
"smtp_security": "starttls"
}
]
}Config is reloaded on each tool call, so changes to accounts.json such as rotating send_code take effect without restarting the MCP server.
Fields
Field | Required | Description |
| No | If set, users must provide this code to send emails. Omit or set to |
| Yes | Short identifier for the account (used in tool calls) |
| Yes | Email address used for IMAP/SMTP login |
| No | Alias address to use as the |
| No | Friendly sender name used in the |
| No | Human-readable label shown by the |
| Yes | Password or app-specific password |
| No | Preset: |
| No | Custom IMAP server (overrides provider default) |
| No | Custom IMAP port (default: 993) |
| No | Custom SMTP server (overrides provider default) |
| No | Custom SMTP port (default: 465) |
| No |
|
Environment variables (single account)
Instead of accounts.json, you can configure a single account via environment variables:
EMAIL_ADDRESS=me@example.com
EMAIL_PASSWORD=password
IMAP_HOST=imap.example.com
SMTP_HOST=smtp.example.com
SMTP_SECURITY=ssl
SEND_AS=alias@example.com
EMAIL_DISPLAY_NAME="Jane Doe"
EMAIL_DESCRIPTION="Primary mailbox"
SEND_CODE=optionalTools
Version 2 exposes a single MCP tool named email. Call it with only an action to discover that action's parameters, then call it again with params.
{"action": "send"}{
"action": "send",
"params": {
"account": "work",
"to": "recipient@example.com",
"subject": "Hello",
"body": "Message body"
}
}Action | Description |
| Validate config without logging into IMAP/SMTP |
| List configured accounts |
| List IMAP folders for an account |
| List recent emails in a folder |
| Search emails using IMAP criteria |
| Read full email content by UID |
| Download an attachment as base64 |
| Inspect local attachment paths before sending |
| Save an attachment directly to disk (preferred for large files) |
| Send an email (text, HTML, attachments, calendar invites) |
| Reply to an email (auto-sets recipient, subject, threading, quotes body) |
| Reply all (sender to To, other recipients to CC, quotes body) |
| Forward an email with original attachments |
| Move an email between folders |
| Mark as read/unread/flagged/unflagged |
list_accounts returns the exact account names plus any configured send_as, display_name, and description, so clients can use the explicit account token instead of guessing partial matches.
Configuration validation
Use validate_config after editing accounts.json or environment variables. It checks required fields, email-like addresses, ports, SMTP security, providers, and placeholder hosts without exposing passwords or logging into IMAP/SMTP.
{
"action": "validate_config",
"params": {}
}Migrating from v1
Most users do not need to change their MCP client configuration. Keep the same simple-email-mcp command and restart the client after upgrading.
The breaking change only affects clients or scripts that call exact v1 tool names such as email_send_email or email_read_email. In v2, use the single email tool with an action instead:
v1 tool | v2 action |
|
|
|
|
|
|
|
|
|
|
|
|
Sending with attachments
Preflight metadata only (recommended before send):
attachments: "/path/to/file.pdf, /path/to/doc.xlsx"Call prepare_attachments first to verify resolved paths, file names, sizes, MIME types, and missing files without loading contents into context.
File path (when the MCP server has filesystem access):
attachments: "/path/to/file.pdf, /path/to/doc.xlsx"Base64 inline (when the caller is in a sandbox):
attachments_inline: [{"filename": "report.pdf", "content_base64": "JVBERi0...", "content_type": "application/pdf"}]Sending calendar invites
Pass raw ICS content via calendar_ics. The email is structured as multipart/alternative so clients display Accept/Decline buttons:
calendar_ics: "BEGIN:VCALENDAR\r\nVERSION:2.0\r\n..."Send confirmation gate
If send_code is set in accounts.json, the AI must show the email draft to the user and wait for them to provide the code before sending. This is useful as a workflow checkpoint to reduce accidental sends.
Important: this is not a hard security boundary if the MCP process and the AI runtime can both read the same config source. In that setup, the AI may be able to read the code from accounts.json or environment variables. Remove or clear send_code to disable the checkpoint.
Testing
Run the regression suite from the repo root:
.venv/bin/python -m unittest discover -s tests -vSecurity
Passwords are stored in
accounts.json— add it to.gitignoreThe
send_codegate is a user-intent checkpoint, not a hard secret, unless the AI cannot read the config source that contains itNo passwords are exposed via the
list_accountsactionFile attachments: The
attachmentsparameter reads files from paths the AI provides. If the MCP server runs with broad filesystem access, the AI could theoretically attach and send any readable file. Useattachments_inline(base64) in sandboxed environments, or restrict filesystem access at the OS/container level.Saving attachments:
save_attachmentfails if the target file already exists unlessoverwrite=trueis set explicitly.
Provider Notes
Gmail
Use an App Password (not your Google password). Enable IMAP in Gmail settings.
Outlook / Microsoft 365
Use an App Password or enable basic auth for IMAP/SMTP.
Purelymail
Use your Purelymail account password directly.
License
MIT — see LICENSE
Authors
Ramon Ramirez (@mexican75)
Available Tools
1 toolemailB
Email client (IMAP/SMTP). Call with just action to discover its parameters. Actions: validate_config, list_accounts, list_folders, list_emails, search, read, send, reply, reply_all, forward, move, mark, save_attachment, get_attachment, prepare_attachments.
Inputs: action (required), params. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
Only one tool exists, so there is no possibility of an agent selecting the wrong tool. The tool's description clearly indicates it is an email client.
With a single tool named 'email', there is no inconsistency in naming patterns across the tool set.
An email client typically requires multiple distinct operations; bundling everything into one tool is an extreme mismatch for the scope.
The tool covers many essential email actions (send, read, list, reply, forward, etc.), but lacks operations like delete or create folder.
Maintenance
Related MCP Connectors
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Email and optional phone for AI agents: send, receive, search, draft and call over MCP.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Related MCP Servers
- FlicenseBqualityCmaintenanceEnables external AI agents to read, send, and manage email over IMAP/SMTP via MCP, including inbox listing, search, drafts, scheduled/batch sending, and operations like reply, archive, and labels.303-
- AlicenseBqualityBmaintenanceConnects MCP clients to any IMAP/SMTP email account, enabling email search, reading, sending, replying, forwarding, flagging, moving, and folder management via natural language.17MIT
- AlicenseNot gradedqualityCmaintenanceConnects MCP-compatible AI assistants to any IMAP/SMTP mailbox, enabling email search, reading, folder management, and sending with automatic saving to Sent.1MIT
- AlicenseBqualityCmaintenanceEnables email integration through MCP, including sending, receiving, searching, replying to, and forwarding emails, plus folder management and multi-account support with encrypted credential storage.40931 npmMIT