Smtp

Email SMTP/IMAP MCP

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

release npm downloads CI OpenSSF Best Practices OpenSSF Baseline Node.js stars license

Why this server

For third-party notices, licence enquiries and the version 2.2.2 supplement, see the open source licence compliance programme.

• 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 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": "[email protected]",
      "password": "app-password"
    },
    "imap": {
      "host": "imap.gmail.com",
      "port": 993,
      "secure": true,
      "user": "[email protected]",
      "password": "app-password"
    },
    "default_from_name": "Your Name",
    "sender_emails": ["[email protected]", "[email protected]"]
  },
  "personal": {
    "smtp": {
      "host": "smtp.mail.me.com",
      "port": 587,
      "secure": false,
      "user": "[email protected]",
      "password": "app-password"
    },
    "imap": {
      "host": "imap.mail.me.com",
      "port": 993,
      "secure": true,
      "user": "[email protected]",
      "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.”

{
  "env": {
    "EMAIL_ACCOUNTS_JSON": "{\"work\":{\"smtp\":{\"host\":\"smtp.gmail.com\",\"port\":587,\"user\":\"[email protected]\",\"password\":\"app-password\"},\"imap\":{\"host\":\"imap.gmail.com\",\"port\":993,\"user\":\"[email protected]\",\"password\":\"app-password\"}}}",
    "DEFAULT_EMAIL_ACCOUNT": "work"
  }
}

Tools

See the tool reference for every input, default, response field and error format.

All tools except accounts_list accept 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. Both SMTP and IMAP require TLS 1.2 or newer and a valid server certificate. With secure: false, STARTTLS is mandatory before authentication; servers without STARTTLS are rejected. Plaintext-only relays are not supported.

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

License

MIT © Sami Halawa

Security and release assurance

Report vulnerabilities through the private route in SECURITY.md. The security assurance programme and source-bound review describe the controls, evidence and publication boundaries for this project. They do not claim an external ISO certificate or completed OpenChain conformance.

Maintainers can run npm run assurance to build the package, run security checks, archive pinned component inputs and verify an offline recovery. The generated release assets include platform-specific build inputs and are intended for durable release retention.