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 forClaude Desktop,Claude Code, and any MCP-compatible client.

git clone https://github.com/mexican75/simple-email-mcp.git cd simple-email-mcp pip install .

{ "accounts": [ { "name": "personal", "address": "me@example.com", "password": "your-app-password", "provider": "gmail" } ] }

claude mcp add email -s user -e ACCOUNTS_FILE=/path/to/accounts.json -- simple-email-mcp

Claude Desktop— add to config (~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS,%APPDATA%\Claude\claude_desktop_config.jsonon Windows):

{ "mcpServers": { "email": { "command": "simple-email-mcp" } } }

{ "mcpServers": { "email": { "command": "python", "args": ["/path/to/simple_email_mcp.py"] } } }

{ "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 toaccounts.jsonsuch as rotatingsend_codetake effect without restarting the MCP server.

Instead ofaccounts.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=optional

Version 2 exposes a single MCP tool namedemail. Call it with only anactionto discover that action's parameters, then call it again withparams.

{ "action": "send", "params": { "account": "work", "to": "recipient@example.com", "subject": "Hello", "body": "Message body" } }

list_accountsreturns the exact account names plus any configuredsend_as,display_name, anddescription, so clients can use the explicit account token instead of guessing partial matches.

Usevalidate_configafter editingaccounts.jsonor 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": {} }

Most users do not need to change their MCP client configuration. Keep the samesimple-email-mcpcommand and restart the client after upgrading.

The breaking change only affects clients or scripts that call exact v1 tool names such asemail_send_emailoremail_read_email. In v2, use the singleemailtool with an action instead:

Preflight metadata only(recommended before send):

attachments: "/path/to/file.pdf, /path/to/doc.xlsx"

Callprepare_attachmentsfirst 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"}]

Pass raw ICS content viacalendar_ics. The email is structured asmultipart/alternativeso clients display Accept/Decline buttons:

calendar_ics: "BEGIN:VCALENDAR\r\nVERSION:2.0\r\n..."

Ifsend_codeis set inaccounts.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 fromaccounts.jsonor environment variables. Remove or clearsend_codeto disable the checkpoint.

Run the regression suite from the repo root:

.venv/bin/python -m unittest discover -s tests -v

- Passwords are stored inaccounts.json—add it to.gitignore
- Thesend_codegate is a user-intent checkpoint, not a hard secret, unless the AI cannot read the config source that contains it
- No passwords are exposed via thelist_accountsaction
- File attachments: Theattachmentsparameter 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.

Use anApp Password(not your Google password). Enable IMAP in Gmail settings.

Use anApp Passwordor enable basic auth for IMAP/SMTP.

Integrate your Fastmail account with AI assistants using the Model Context Protocol.