Email SMTP/IMAP MCP

One local MCP server for every inbox: search, read, send, reply, forward, and organize email across multiple accounts.

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.

Related MCP server: Email Server

Quick start

1. Create your .env

Copy .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.”

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

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:

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.

Tools

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

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 ..

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.

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:

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:

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:

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:

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:

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 for the development workflow and SECURITY.md for vulnerability reports.

License

MIT © Sami Halawa