Email MCP Server

A clean, simple 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\":\"your@gmail.com\",\"password\":\"app-password\"},\"imap\":{\"host\":\"imap.gmail.com\",\"port\":993},\"default_from_name\":\"Your Name\",\"sender_emails\":[\"your@gmail.com\"]}}",
        "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\":\"your@gmail.com\",\"password\":\"app-password\"},\"imap\":{\"host\":\"imap.gmail.com\",\"port\":993},\"default_from_name\":\"Your Name\",\"sender_emails\":[\"your@gmail.com\"]}}"

Setup: Create App Password

iCloud Mail

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

Setup: Generate App-Specific Password

Outlook/Office 365

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

Multiple Accounts

"EMAIL_ACCOUNTS_JSON": "{\"work\":{\"smtp\":{\"host\":\"smtp.gmail.com\",\"port\":587,\"user\":\"work@company.com\",\"password\":\"app-password\"},\"imap\":{\"host\":\"imap.gmail.com\",\"port\":993},\"default_from_name\":\"John Doe\"},\"personal\":{\"smtp\":{\"host\":\"smtp.mail.me.com\",\"port\":587,\"user\":\"me@icloud.com\",\"password\":\"app-password\"},\"imap\":{\"host\":\"imap.mail.me.com\",\"port\":993},\"default_from_name\":\"John\"}}",
"DEFAULT_EMAIL_ACCOUNT": "work"

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 team@company.com 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 newsletter@site.com 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