Email SMTP/IMAP MCP
by EhanAhmed
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.
For SMTP sending only, the IMAP variables can be omitted:
```dotenv
SMTP_HOST="smtp.gmail.com"
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER="you@gmail.com"
SMTP_PASS="your-16-character-app-password"
DEFAULT_FROM_NAME="Your Name"
SENDER_EMAILS="you@gmail.com"
```
Add the IMAP variables only when you also want to search, read, reply to, or organize messages.
</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 .`.
## Docker Compose
Compose runs the MCP server over Streamable HTTP so it can stay up as a detached container. This setup expects the external `litellm-langfuse-net` Docker network to exist and LiteLLM to be connected to it.
```bash
cp .env.example .env
# Edit .env and add your SMTP/IMAP account details.
docker compose up --build -d
```
The server listens on port `8000` inside the Docker network at `/mcp`. The Compose file exposes the port to other containers but does not publish it on the host. It mounts `.env` read-only; do not commit that file because it contains email credentials. Use app-specific passwords where your provider supports them.
Add this to LiteLLM's `config.yaml`:
```yaml
mcp_servers:
email:
url: http://email-mcp:8000/mcp
transport: http
```
`email-mcp` is the Compose service name and resolves through Docker DNS on `litellm-langfuse-net`. No Docker socket mount or host port publishing is needed when LiteLLM is on that same network. Restart LiteLLM after changing its config, then verify that `accounts_list` and the other tools appear. Calling `email_send` sends a real message.
Check the container with `docker compose ps` and `docker compose logs email-mcp`. Keep this endpoint on the trusted Docker network; it does not add HTTP authentication.
### Keep Using Stdio
The server still defaults to stdio for direct Node.js MCP clients. To use this Compose service as a stdio child process instead, override the HTTP setting when invoking it:
```bash
docker compose run --rm -T -e MCP_TRANSPORT=stdio email-mcp
```
For LiteLLM stdio mode, configure `command: docker` with arguments `compose`, `-f`, the absolute path to this repository's `docker-compose.yml`, `run`, `--rm`, `-T`, `-e`, `MCP_TRANSPORT=stdio`, and `email-mcp`. In this mode LiteLLM launches the process; do not point its stdio configuration at the already-detached HTTP service.
### Recreate the Setup on Another System
1. Install Docker Compose, then clone this repository:
```bash
git clone <repository-url> email-smtp-imap-mcp
cd email-smtp-imap-mcp
cp .env.example .env
```
2. Edit `.env` with the SMTP credentials, sender allowlist, and optional `DEFAULT_TO_EMAIL`. Do not copy the old app password into source control; create a new provider app password when moving systems.
3. Build and verify the MCP:
```bash
npm ci
npm run build
docker compose build
docker compose config --quiet
```
4. Ensure the external Docker network exists and attach LiteLLM to `litellm-langfuse-net`. The email Compose service uses that network and listens at `email-mcp:8000`.
5. In the LiteLLM `config.yaml`, configure the remote HTTP MCP server:
```yaml
mcp_servers:
email:
url: http://email-mcp:8000/mcp
transport: http
```
6. Start the email MCP with `docker compose up --build -d`, then reload LiteLLM using the normal deployment procedure. Confirm that `accounts_list`, `emails_find`, `email_send`, `email_respond`, `emails_modify`, and `folders_list` are visible. Do not call `email_send` during setup verification unless you intend to send a real email.
## 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
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues