Email SMTP/IMAP MCP Server
by samihalawa
README.md
<p align="center">
<img src="./docs/assets/email-mcp-hero.png" alt="One MCP server connecting multiple email accounts" width="100%" />
</p>
# Email SMTP/IMAP MCP
One local MCP server for every inbox: search, read, send, reply, forward, and organize email across multiple accounts.
[](https://github.com/samihalawa/email-smtp-imap-mcp/releases/latest)
[](https://www.npmjs.com/package/email-smtp-imap-mcp)
[](https://www.npmjs.com/package/email-smtp-imap-mcp)
[](https://github.com/samihalawa/email-smtp-imap-mcp/actions/workflows/ci.yml)
[](https://nodejs.org/)
[](https://github.com/samihalawa/email-smtp-imap-mcp/stargazers)
[](LICENSE)
## Why this server
- **No account-count cap** — add work, personal, support, or client inboxes and switch with `account_name`.
- **SMTP + IMAP together** — send and receive through one small MCP server.
- **Complete everyday workflow** — search, read, reply, forward, attach files, flag, archive, move, and list folders.
- **Provider-agnostic** — works with Gmail, iCloud Mail, Fastmail, Outlook, self-hosted mail, and other standard SMTP/IMAP providers.
- **Local stdio transport** — no hosted relay and no separate control panel.
<p align="center">
<img src="./docs/assets/email-mcp-features.png" alt="Search, send, respond, organize, and browse folders across accounts" width="100%" />
</p>
## Quick start
### 1. Create your `.env`
Copy [.env.example](.env.example) to a private location and add as many named accounts as you need:
```dotenv
EMAIL_ACCOUNTS_JSON='{
"work": {
"smtp": {
"host": "smtp.gmail.com",
"port": 587,
"secure": false,
"user": "work@example.com",
"password": "app-password"
},
"imap": {
"host": "imap.gmail.com",
"port": 993,
"secure": true,
"user": "work@example.com",
"password": "app-password"
},
"default_from_name": "Your Name",
"sender_emails": ["work@example.com", "alias@example.com"]
},
"personal": {
"smtp": {
"host": "smtp.mail.me.com",
"port": 587,
"secure": false,
"user": "you@icloud.com",
"password": "app-password"
},
"imap": {
"host": "imap.mail.me.com",
"port": 993,
"secure": true,
"user": "you@icloud.com",
"password": "app-password"
}
}
}'
DEFAULT_EMAIL_ACCOUNT="work"
```
The server loads `.env` from its working directory automatically. `EMAIL_ENV_FILE` lets an MCP client use an `.env` stored anywhere.
### 2. Add the MCP server
For Claude Desktop, edit:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"email": {
"command": "npx",
"args": ["-y", "email-smtp-imap-mcp"],
"env": {
"EMAIL_ENV_FILE": "/absolute/path/to/your/.env"
}
}
}
}
```
Use an absolute path, restart your MCP client, then ask: **“List my configured email accounts.”**
<details>
<summary>Pass account JSON directly from the MCP client</summary>
You can skip the `.env` file and set `EMAIL_ACCOUNTS_JSON` plus `DEFAULT_EMAIL_ACCOUNT` directly in the MCP client’s `env` object. The JSON must be escaped into a single string.
```json
{
"env": {
"EMAIL_ACCOUNTS_JSON": "{\"work\":{\"smtp\":{\"host\":\"smtp.gmail.com\",\"port\":587,\"user\":\"work@example.com\",\"password\":\"app-password\"},\"imap\":{\"host\":\"imap.gmail.com\",\"port\":993,\"user\":\"work@example.com\",\"password\":\"app-password\"}}}",
"DEFAULT_EMAIL_ACCOUNT": "work"
}
}
```
</details>
<details>
<summary>Single-account `.env` variables</summary>
Use `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER`, `SMTP_PASS`, `IMAP_HOST`, `IMAP_PORT`, `IMAP_SECURE`, `IMAP_USER`, and `IMAP_PASS` instead of `EMAIL_ACCOUNTS_JSON`.
`SMTP_USERNAME`/`SMTP_PASSWORD` and `IMAP_USERNAME`/`IMAP_PASSWORD` are accepted aliases. IMAP credentials default to the SMTP credentials when omitted. Use `SENDER_EMAILS` as a comma-separated allowlist for optional `from_email` selection.
</details>
## Tools
| Tool | What it does |
| --- | --- |
| `accounts_list` | List every configured account and identify the default without exposing credentials. |
| `emails_find` | Search by text, sender, recipient, subject, date, read state, flag state, or attachments. Optionally return bodies and attachments. |
| `email_send` | Send plain-text or HTML email with CC, BCC, sender aliases, and base64 attachments. |
| `email_respond` | Reply, reply-all, or forward by email UID with threading and optional original attachments. |
| `emails_modify` | Mark read/unread, flag/unflag, or move messages to another folder. |
| `folders_list` | List folders with optional total and unread counts. |
Every email tool accepts an optional `account_name`. Without it, the server uses `DEFAULT_EMAIL_ACCOUNT` or the first configured account. There is no application-level account-count limit.
## Verify your setup
After restarting the MCP client, try these in order:
1. “List my configured email accounts.”
2. “List folders for my `work` account.”
3. “Find the five newest unread emails in my `personal` account.”
4. “Send a plain-text email from my `work` account.”
## Provider settings
| Provider | SMTP | IMAP | Credential |
| --- | --- | --- | --- |
| Gmail | `smtp.gmail.com:587` | `imap.gmail.com:993` | [App password](https://support.google.com/accounts/answer/185833) |
| iCloud Mail | `smtp.mail.me.com:587` | `imap.mail.me.com:993` | [App-specific password](https://support.apple.com/en-us/102654) |
| Other providers | Use the provider's SMTP host | Use the provider's IMAP host | Provider password or app password |
Use `secure: true` for implicit TLS ports such as 465/993. Port 587 normally uses `secure: false` and upgrades with STARTTLS.
## Development
```bash
git clone https://github.com/samihalawa/email-smtp-imap-mcp.git
cd email-smtp-imap-mcp
npm ci
npm test
```
Run the compiled stdio server with `npm start`. Build a production container with `docker build -t email-smtp-imap-mcp .`.
## Contributing
Issues and focused pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and [SECURITY.md](SECURITY.md) for vulnerability reports.
## License
[MIT](LICENSE) © Sami Halawa
TDQS
A3.6/5.0
Scored across 5 tools
Disambiguation5/5
Each tool has a clearly distinct purpose with no overlap: email_respond handles replies/forwards, email_send creates new emails, emails_find searches, emails_modify changes states, and folders_list enumerates folders. The descriptions reinforce these distinct roles, making tool selection unambiguous.
Naming Consistency4/5
The naming is mostly consistent with a verb_noun pattern (e.g., email_send, emails_find, folders_list), but there is a minor deviation with email_respond (verb_noun) versus emails_modify (plural_noun_verb). This small inconsistency slightly reduces predictability but remains readable.
Tool Count5/5
With 5 tools, the server is well-scoped for email management. Each tool earns its place by covering core email operations: sending, replying, searching, modifying, and listing folders. This count is appropriate and avoids bloat or thin coverage.
Completeness4/5
The tool set provides strong coverage for email workflows, including CRUD-like actions (send, find, modify) and folder management. A minor gap is the lack of a tool for creating or deleting folders, but agents can still handle most email tasks effectively with the available tools.
Maintenance
ActivityMaintained
ResponsivenessSlow