Email Smtp Imap Mcp

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.

Quick start

1. Create your .env

Copy [.env.example](.env.example) to a private location and add as many named accounts as you need:

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

{
  "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.”

Pass account JSON directly from the MCP client

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.

{
  "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"
  }
}

Single-account .env variables

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.

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 | | iCloud Mail | smtp.mail.me.com:587 | imap.mail.me.com:993 | App-specific password | | 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

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: samihalawa
• Source: samihalawa/email-smtp-imap-mcp
• License: MIT
• Homepage: https://www.npmjs.com/package/email-smtp-imap-mcp

Install and usage instructions live in the source repository linked above.