Email MCP Server

A clean, simple stdio MCP server for email operations supporting both SMTP (sending) and IMAP (reading).

Features

• ✅ Send emails with HTML and attachments
• ✅ Search emails with flexible filters
• ✅ Reply/Forward with proper threading
• ✅ Organize (mark read, archive, flag)
• ✅ Multi-account support for managing multiple email accounts
• ✅ List folders to browse your mailbox structure

Quick Start

Installation

npx -y email-smtp-imap-mcp

Or install globally:

npm install -g email-smtp-imap-mcp

Configuration

Add to your Claude Desktop config file:

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_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_from_name\":\"Your Name\",\"sender_emails\":[\"[email protected]\"]}}",
        "DEFAULT_EMAIL_ACCOUNT": "work"
      }
    }
  }
}

⚠️ Important: Restart Claude Desktop after adding this configuration.

Email Provider Settings

Gmail

"EMAIL_ACCOUNTS_JSON": "{\"gmail\":{\"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_from_name\":\"Your Name\",\"sender_emails\":[\"[email protected]\"]}}"

Setup: Create App Password

iCloud Mail

"EMAIL_ACCOUNTS_JSON": "{\"icloud\":{\"smtp\":{\"host\":\"smtp.mail.me.com\",\"port\":587,\"user\":\"[email protected]\",\"password\":\"app-specific-password\"},\"imap\":{\"host\":\"imap.mail.me.com\",\"port\":993,\"user\":\"[email protected]\",\"password\":\"app-specific-password\"},\"default_from_name\":\"Your Name\",\"sender_emails\":[\"[email protected]\"]}}"

Setup: Generate App-Specific Password

Outlook/Office 365

"EMAIL_ACCOUNTS_JSON": "{\"outlook\":{\"smtp\":{\"host\":\"smtp-mail.outlook.com\",\"port\":587,\"user\":\"[email protected]\",\"password\":\"your-password\"},\"imap\":{\"host\":\"outlook.office365.com\",\"port\":993,\"user\":\"[email protected]\",\"password\":\"your-password\"},\"default_from_name\":\"Your Name\",\"sender_emails\":[\"[email protected]\"]}}"

Multiple Accounts

"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_from_name\":\"John Doe\"},\"personal\":{\"smtp\":{\"host\":\"smtp.mail.me.com\",\"port\":587,\"user\":\"[email protected]\",\"password\":\"app-password\"},\"imap\":{\"host\":\"imap.mail.me.com\",\"port\":993,\"user\":\"[email protected]\",\"password\":\"app-password\"},\"default_from_name\":\"John\"}}",
"DEFAULT_EMAIL_ACCOUNT": "work"

The server also accepts flat or single-account environment variables. For compatibility, SMTP_USERNAME/SMTP_PASSWORD are aliases for SMTP_USER/SMTP_PASS, IMAP_USERNAME/IMAP_PASSWORD are aliases for IMAP_USER/IMAP_PASS, and IMAP_USER/IMAP_PASS fall back to the SMTP credentials when omitted.

Available Tools

| Tool | Description | |------|-------------| | emails_find | Search emails with flexible filters (sender, subject, date, attachments, etc.) | | emails_modify | Mark as read/unread, flag, archive, or move emails | | email_send | Send new emails with HTML content and attachments | | email_respond | Reply or forward emails with proper threading | | folders_list | List all available email folders |

Usage Examples

Ask Claude to:

• "Find unread emails from last week"
• "Send an email to [email protected] about the meeting"
• "Reply to the last email from Sarah"
• "Archive all emails older than 30 days"
• "List my email folders"
• "Find emails with attachments from my boss"
• "Mark all emails from [email protected] as read"

Security Notes

• Never commit .env files or credentials to version control
• Use app-specific passwords or app passwords, not your main account password
• The server runs locally on your machine - credentials stay private
• All email connections use TLS encryption (ports 587 for SMTP, 993 for IMAP)

Development

# Clone the repository
git clone https://github.com/samihalawa/email-smtp-imap-mcp.git
cd email-smtp-imap-mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

Troubleshooting

Authentication Errors

• Make sure you're using an app password, not your regular password
• For Gmail: Create App Password
• For iCloud: Generate App-Specific Password

Server Not Starting

• Verify your configuration JSON is properly escaped
• Check that ports 587 (SMTP) and 993 (IMAP) are not blocked by your firewall
• Restart Claude Desktop after configuration changes

Connection Issues

• Confirm your email provider allows IMAP/SMTP access
• Check your internet connection
• Verify the SMTP/IMAP host and port settings for your provider

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Sami Halawa - GitHub

Made with ❤️ for the MCP community