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