Content
# Tool List
[](https://badge.fury.io/js/mcp-email)
[](https://www.npmjs.com/package/mcp-email)
[](https://opensource.org/licenses/MIT)
A universal MCP server for AI to easily take over email accounts, built based on Model Context Protocol (MCP), supporting MCP-X, Claude Desktop, and other MCP clients.
**Automatic configuration support for multiple email service providers**: QQ Mail, 163 Mail, Gmail, Outlook, Tencent Enterprise Mail, NetEase Enterprise Mail, Alibaba Cloud Mail, Sina Mail, Sohu Mail, etc.
## Quick Installation
```bash
# npm installation
npm install -g mcp-email
# Run with npx (recommended)
npx mcp-email
```
## Features
- 📤 **Email sending**: Supports sending HTML and plain text emails
- 👥 **Multiple recipients**: Supports multiple recipients, CC, and BCC
- 📎 **Attachment support**: Supports file attachments and Base64 encoded content
- 🔧 **Dynamic configuration**: Supports runtime configuration of email servers
- 🔍 **Connection testing**: Built-in SMTP server connection testing
- 🛡️ **Security authentication**: Supports WeChat Enterprise Mail authorization code authentication
- ⚡ **High performance**: Optimized connection timeout and retry mechanism
## Detailed Configuration Guide
The project provides a detailed configuration guide, including configuration instructions for major email service providers:
📖 **[CONFIG_GUIDE.md](./CONFIG_GUIDE.md)** - Complete configuration guide, including:
- 📧 163 Mail detailed configuration tutorial
- 🏢 WeChat Enterprise Mail configuration guide
- 🌐 QQ Mail, Gmail, and other mainstream email configuration
- 🛠️ Troubleshooting and common problem solutions
## System Requirements
- Node.js 16.x or higher
- Email account
- MCP client (such as Claude Desktop)
## Quick Start
### Method 1: Directly use npm package (recommended)
#### 1. Install npm package
```bash
# Global installation
npm install -g mcp-email
# Or local installation
npm install mcp-email
```
#### 2. Configure in MCP client
**MCP-X configuration example:**
```json
{
"mcpServers": {
"universal-email": {
"command": "npx",
"args": ["mcp-email"],
"env": {
"EMAIL_USER": "your-email@domain.com",
"EMAIL_PASSWORD": "your-password-or-auth-code",
"EMAIL_TYPE": "auto"
}
}
}
}
```
### Method 2: Install from source
#### 1. Clone project
```bash
git clone https://github.com/TimeCyber/email-mcp.git
cd email-mcp
```
#### 2. Install dependencies
```bash
npm install
```
#### 3. Configure MCP client (source installation)
**MCP-X configuration:**
```json
{
"mcpServers": {
"universal-email": {
"command": "node",
"args": ["F:\\path\\to\\email-mcp\\index.js"],
"env": {
"EMAIL_USER": "your-email@domain.com",
"EMAIL_PASSWORD": "your-password-or-auth-code",
"EMAIL_TYPE": "auto"
}
}
}
}
```
**Enterprise mail configuration:**
```json
{
"mcpServers": {
"enterprise-email": {
"command": "node",
"args": ["F:\\path\\to\\email-mcp\\index.js"],
"env": {
"EMAIL_USER": "user@company.com",
"EMAIL_PASSWORD": "your-enterprise-auth-code",
"EMAIL_TYPE": "exmail"
}
}
}
}
```
#### 4. Test configuration
```bash
# Test email configuration
node test-auto-config.js
```
## Email Configuration Guide
### Obtain authorization code
Different email authorization code acquisition methods:
**Tencent Enterprise Mail:**
1. Visit [Enterprise Mail Management Background](https://exmail.qq.com/)
2. Enter **"Settings"** → **"Account"** → **"Client-specific password"**
3. Generate **Client-specific password** (authorization code)
4. Enter **"Settings"** → **"Send and receive settings"** → **"Settings"**
5. Enable **"POP/IMAP/SMTP service"**
**QQ Mail:**
1. Log in to QQ Mail, enter **"Settings"** → **"Account"**
2. Enable **"POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV service"**
3. Generate authorization code
**163 Mail:**
1. Log in to 163 Mail, enter **"Settings"** → **"POP3/SMTP/IMAP"**
2. Enable **"POP3/SMTP/IMAP service"**
3. Set client authorization password
💡 **Key tips**:
- Enterprise mail must set `EMAIL_TYPE` field!
- Personal mail can use `EMAIL_TYPE: "auto"` for automatic identification
📖 **[CONFIG_GUIDE.md](./CONFIG_GUIDE.md)** - Complete configuration guide, including detailed instructions for all email types
## MCP Tool Description
### 1. `send_email` - Send email
Send email, support multiple formats and recipients.
#### Parameters
- **`to`** (required): Recipient email address array
- **`subject`** (required): Email subject
- **`text`** (required): Plain text email content
- **`cc`** (optional): CC email address array
- **`bcc`** (optional): BCC email address array
- **`html`** (optional): HTML format email content
- **`attachments`** (optional): Attachment array
#### Example usage
**Basic email sending:**
```json
{
"to": ["recipient@example.com"],
"subject": "Test email",
"text": "This is a test email"
}
```
**With CC and HTML content:**
```json
{
"to": ["recipient1@example.com", "recipient2@example.com"],
"cc": ["manager@example.com"],
"subject": "Project report",
"text": "Please view the project report",
"html": "<h1>Project report</h1><p>Project progress is smooth.</p>"
}
```
**Email with attachment:**
```json
{
"to": ["recipient@example.com"],
"subject": "Email with attachment",
"text": "Please view the attachment",
"attachments": [
{
"filename": "report.pdf",
"path": "C:\\path\\to\\report.pdf"
},
{
"filename": "data.txt",
"content": "SGVsbG8gV29ybGQ="
}
]
}
```
### 2. `get_recent_emails` - Get recent emails
Get a list of recent emails, automatically select the best protocol (IMAP/POP3).
#### Parameters
- **`limit`** (optional): Return email quantity limit, default 20
- **`days`** (optional): Get recent days of emails, default 3 days
#### Example usage
```json
{
"limit": 10,
"days": 7
}
```
### 3. `get_email_content` - Get email content
Get the detailed content of the specified email.
#### Parameters
- **`uid`** (required): Email unique identifier (obtained from email list)
#### Example usage
```json
{
"uid": "12345"
}
```
### 4. `setup_email_account` - Set up email account
Automatically identify email type and configure server, support 8 major email service providers.
#### Parameters
- **`email`** (required): Email address
- **`password`** (required): Email password or authorization code
- **`provider`** (optional): Email provider (manually specified for enterprise mail)
#### Supported email types
- `qq` - QQ Mail
- `163` - NetEase Mail
- `gmail` - Gmail
- `outlook` - Outlook/Hotmail
- `exmail` - Tencent Enterprise Mail
- `netease-enterprise` - NetEase Enterprise Mail
- `aliyun` - Alibaba Cloud Mail
- `sina` - Sina Mail
- `sohu` - Sohu Mail
#### Example usage
**Personal mail (automatic identification):**
```json
{
"email": "user@qq.com",
"password": "your-auth-code"
}
```
**Enterprise mail (manual specification):**
```json
{
"email": "user@company.com",
"password": "your-enterprise-auth-code",
"provider": "exmail"
}
```
### 5. `list_supported_providers` - List supported email providers
View all supported email service providers and their configuration information.
#### Parameters
No parameters required
#### Example usage
```json
{}
```
### 6. `configure_email_server` - Manually configure server
Manually configure email server settings (for advanced users).
#### Parameters
- **`user`** (required): Email account
- **`password`** (required): Email password or authorization code
- **`smtpHost`** (optional): SMTP server address
- **`smtpPort`** (optional): SMTP port
- **`smtpSecure`** (optional): Whether to use SSL
- **`imapHost`** (optional): IMAP server address
- **`imapPort`** (optional): IMAP port
- **`imapSecure`** (optional): Whether to use SSL
#### Example usage
```json
{
"user": "your-email@domain.com",
"password": "your-password",
"smtpHost": "smtp.domain.com",
"smtpPort": 465,
"smtpSecure": true
}
```
### 7. `test_email_connection` - Test connection
Test email server connection status.
#### Parameters
- **`testType`** (optional): Test type
- `smtp` - Test send server only
- `imap` - Test receive server only
- `both` - Test all (default)
#### Example usage
```json
{
"testType": "smtp"
}
```
## Supported Email Service Providers
### Mainstream email server configuration
| Email type | SMTP server | SMTP port | IMAP server | IMAP port | Recommended protocol |
|---------|------------|----------|------------|----------|----------|
| QQ Mail | smtp.qq.com | 587 | imap.qq.com | 993 | IMAP |
| NetEase Mail | smtp.163.com | 465 | imap.163.com | 993 | POP3* |
| Gmail* | smtp.gmail.com | 587 | imap.gmail.com | 993 | IMAP |
| Outlook | smtp-mail.outlook.com | 587 | outlook.office365.com | 993 | IMAP |
| Tencent Enterprise Mail | smtp.exmail.qq.com | 465 | imap.exmail.qq.com | 993 | IMAP |
<!--- | NetEase Enterprise Mail | smtphz.qiye.163.com | 994 | imaphz.qiye.163.com | 993 | POP3* | --->
| Alibaba Cloud Mail | smtp.mxhichina.com | 465 | imap.mxhichina.com | 993 | IMAP |
***NetEase Mail (163/126/yeah) automatically uses POP3 protocol to avoid "Unsafe Login" error**
***Gmail special note**: From May 1, 2025, Google Workspace accounts no longer support "less secure apps", and must use OAuth authentication. Personal Gmail needs to use app-specific password. See [configuration guide](CONFIG_GUIDE.md#gmail-detailed-configuration-tutorial).**
### Automatic configuration features
- ✅ **Intelligent recognition**: Automatically select server configuration based on email domain
- ✅ **Protocol optimization**: 163 Mail automatically uses POP3, others use IMAP
- ✅ **Enterprise mail**: Support manual specification through `EMAIL_TYPE` field
- ✅ **Error handling**: Automatically try POP3 protocol when IMAP fails
## Troubleshooting
### Common errors and solutions
#### 1. `535 Error: authentication failed`
**Cause**: Authentication failed
**Solution**:
- Confirm SMTP/IMAP/POP3 service is enabled in email settings
- Regenerate authorization code or application-specific password
- Check email address and authorization code are correct
- For enterprise mail, confirm administrator has allowed third-party access
#### 2. `[IMAP] EXAMINE Unsafe Login` (common in NetEase Mail)
**Cause**: NetEase Mail security restrictions
**Solution**:
- System will automatically switch to POP3 protocol
- Confirm POP3/SMTP service is enabled in NetEase Mail
- Use latest generated 16-digit authorization code
#### 3. `ECONNREFUSED` or connection timeout
**Cause**: Network connection issue
**Solution**:
- Check network connection status
- Confirm firewall is not blocking email ports (25, 465, 587, 993, 995)
- Try different network environments or VPN
#### 4. `EMAIL_TYPE` related errors
**Cause**: Enterprise mail domain and server mismatch
**Solution**:
- Set correct `EMAIL_TYPE` field for enterprise mail
- Tencent Enterprise Mail set to `"exmail"`
- NetEase Enterprise Mail set to `"netease-enterprise"`
### Diagnostic tools
Use built-in diagnostic commands:
```bash
# Test email configuration
node test-auto-config.js
# Test EMAIL_TYPE function
node test-email-type.js
# Use MCP tool to test connection
# Call `test_email_connection` in MCP client
```
### Debugging tips
1. **View detailed logs**: System will automatically output configuration and connection information
2. **Use testing tools**: Diagnose issues through `test_email_connection`
3. **Check email type**: Use `list_supported_providers` to confirm support
4. **Step-by-step configuration**: First use `setup_email_account` for automatic configuration
## Project structure
```
├── index.js # Main MCP server program
├── package.json # Project dependency configuration
├── README.md # Project main document
├── CONFIG_GUIDE.md # Detailed configuration guide
├── .gitignore # Git ignore file
├── 📁 Configuration templates/
│ ├── mcp-x_config_v2.json # General configuration template
│ └── mcp-x_config_multi.json # Multi-account configuration
├── 📁 Testing tools/
│ ├── test-auto-config.js # Automatic configuration test
│ └── test-email-type.js # EMAIL_TYPE function test
└── LICENSE # Open-source license
```
### Core file description
- **`index.js`** - Main MCP server program, including all email functions
- **`CONFIG_GUIDE.md`** - Detailed configuration guide, including various email configuration instructions
- **`mcp-x_config_v2.json`** - General configuration template, supporting EMAIL_TYPE field
- **`test-auto-config.js`** - Test automatic configuration script
- **`test-email-type.js`** - Verify EMAIL_TYPE field function test script
## Security considerations
1. **Protect authorization code**: Do not submit authorization code to version control system
2. **Use environment variables**: Recommended to store sensitive information using environment variables
3. **Regular update**: Regularly update authorization code and check security settings
4. **Permission control**: Ensure only authorized users can access MCP server
## Technical support
### 📖 Document resources
- 📋 **[CONFIG_GUIDE.md](./CONFIG_GUIDE.md)** - Complete configuration guide
- 🔧 **Testing tools** - Use `test-auto-config.js` and `test-email-type.js`
- 🛠️ **Built-in diagnosis** - Use `test_email_connection` tool
### 🌐 Official documents
- [NetEase Mail client settings](https://help.mail.163.com/faqDetail.do?code=d7a5dc8471cd0c0e8b4b8f4f8e49998b374173cfe9171305fa1ce630d7f67ac2a5feb28b66796d3b)
- [Tencent Enterprise Mail configuration](https://open.work.weixin.qq.com/help2/pc/19886?person_id=1)
- [QQ Mail help center](https://kf.qq.com/product/tx_mail.html)
- [Gmail settings guide](https://support.google.com/mail/answer/7126229)
### 🤝 Contribution guide
Welcome to submit issues and pull requests to improve this project!
- 🐛 **Report bugs**: Please describe issues and reproduction steps in detail
- 💡 **Feature suggestions**: Welcome to propose new email support requirements
- 📝 **Documentation improvement**: Help improve usage documents
### 📊 Project status
- ✅ **Production ready**: Support 8 major email service providers
- 🔄 **Continuous update**: Continuously improve based on user feedback
- 🛡️ **Security guarantee**: Support SSL/TLS encryption and authorization code authentication
## 📄 License
MIT License - See [LICENSE](./LICENSE) file
---
## 🎉 Quick test
After configuration, test functions in MCP client:
**Send test email:**
```
Please send a test email to test@example.com, subject "MCP test email", content "Hello from Universal Email MCP!"
```
**Get email list:**
```
Please get recent 3-day email list, limit 10 emails
```
**Test connection:**
```
Please test email connection status
```
If everything is configured correctly, all functions should work normally!
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available