Email MCP

🚀 Universal Email MCP Server

A universal MCP server that enables AI to easily take over email, built on the Model Context Protocol (MCP). It supports use in MCP clients such as MCP-X and Claude Desktop.

• Support for automatic configuration of 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 Start

Method 1: Use the npm package directly (Recommended)

1. Install the npm package

# Install globally
npm install -g mcp-email

# Or install locally
npm install mcp-email

2. Configure in the MCP client

Configuration example for MCP-X:

{
  "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 code

1. Clone the project

git clone https://github.com/TimeCyber/email-mcp.git
cd email-mcp

2. Install dependencies

npm install

3. Configure the MCP client (for source code installation)

Configuration for MCP-X:

{
  "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"
      }
    }
  }
}

Configuration for enterprise email:

{
  "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 the configuration

# Test if the email configuration is successful
node test-auto-config.js

✨ Features

• 📤 Email sending: Supports sending HTML and plain text emails.
• 👥 Multiple recipients: Supports multiple recipients, carbon copies, and blind carbon copies.
• 📎 Attachment support: Supports file attachments and Base64-encoded content.
• 🔧 Dynamic configuration: Supports configuring the email server at runtime.
• 🔍 Connection test: Built-in SMTP server connection test.
• 🛡️ Secure authentication: Supports authorization code authentication for WeChat Enterprise Mail.
• ⚡ High performance: Optimized connection timeout and retry mechanism.

📦 Installation

# Install via npm
npm install -g mcp-email

# Run using npx (Recommended)
npx mcp-email

💻 Usage Examples

Basic Usage

Sending a basic email

{
  "to": ["recipient@example.com"],
  "subject": "Test Email",
  "text": "This is a test email"
}

Sending an email with carbon copy and HTML content

{
  "to": ["recipient1@example.com", "recipient2@example.com"],
  "cc": ["manager@example.com"],
  "subject": "Project Report",
  "text": "Please check the project report",
  "html": "<h1>Project Report</h1><p>The project is progressing smoothly.</p>"
}

Sending an email with attachments

{
  "to": ["recipient@example.com"],
  "subject": "Email with Attachments",
  "text": "Please check the attachments",
  "attachments": [
    {
      "filename": "report.pdf",
      "path": "C:\\path\\to\\report.pdf"
    },
    {
      "filename": "data.txt",
      "content": "SGVsbG8gV29ybGQ="
    }
  ]
}

Advanced Usage

Getting recent emails

{
  "limit": 10,
  "days": 7
}

Getting email content

{
  "uid": "12345"
}

Setting up an email account

{
  "email": "user@qq.com",
  "password": "your-auth-code"
}

Listing supported email providers

{}

Manually configuring the email server

{
  "user": "your-email@domain.com",
  "password": "your-password",
  "smtpHost": "smtp.domain.com",
  "smtpPort": 465,
  "smtpSecure": true
}

Testing the email connection

{
  "testType": "smtp"
}

📚 Documentation

The project provides a detailed configuration guide, including configuration instructions for major email service providers:

📖 CONFIG_GUIDE.md - Complete configuration guide, including:

• 📧 Detailed configuration tutorial for 163 Mail
• 🏢 Configuration guide for WeChat Enterprise Mail
• 🌐 Configuration for mainstream emails such as QQ Mail and Gmail
• 🛠️ Troubleshooting and solutions to common problems

🔧 Technical Details

System Requirements

• Node.js 16.x or higher
• Email account
• MCP client (e.g., Claude Desktop)

MCP Tool Instructions

1. send_email - Send an email

Send an email, supporting multiple formats and recipients.

Parameters:

• to (Required): Array of recipient email addresses.
• subject (Required): Email subject.
• text (Required): Plain text email content.
• cc (Optional): Array of carbon copy email addresses.
• bcc (Optional): Array of blind carbon copy email addresses.
• html (Optional): HTML format email content.
• attachments (Optional): Array of attachments.

2. get_recent_emails - Get recent emails

Get a list of recent emails, automatically selecting the best protocol (IMAP/POP3).

Parameters:

• limit (Optional): Limit the number of returned emails, default is 20.
• days (Optional): Get emails from the recent days, default is 3 days.

3. get_email_content - Get email content

Get the detailed content of a specified email.

Parameters:

• uid (Required): Unique identifier of the email (obtained from the email list).

4. setup_email_account - Set up an email account

Automatically identify the email type and configure the server, supporting 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 emails).

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

5. list_supported_providers - List supported email providers

View all supported email service providers and their configuration information.

Parameters: No parameters required.

6. configure_email_server - Manually configure the server

Manually configure the 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.

7. test_email_connection - Test the connection

Test the email server connection status.

Parameters:

• testType (Optional): Test type.
  • smtp - Test only the sending server.
  • imap - Test only the receiving server.
  • both - Test all (default).

Supported Email Service Providers

Configuration of mainstream email servers

*NetEase Mail (163/126/yeah) automatically uses the POP3 protocol to avoid the "Unsafe Login" error.

Special note for Gmail: Starting from May 1, 2025, Google Workspace accounts will no longer support "less secure apps" and must use OAuth authentication. Personal Gmail accounts need to use app-specific passwords. See Configuration Guide for details.

Automatic Configuration Features

• ✅ Intelligent recognition: Automatically selects the server configuration based on the email domain name.
• ✅ Protocol optimization: NetEase Mail automatically uses POP3, others use IMAP.
• ✅ Enterprise mail: Supports manual specification through the EMAIL_TYPE field.
• ✅ Error handling: Automatically tries the POP3 protocol when IMAP fails.

Troubleshooting

Common errors and solutions

1. 535 Error: authentication failed

Cause: Authentication failed. Solution:

• Confirm that SMTP/IMAP/POP3 services are enabled in the email settings.
• Regenerate the authorization code or app-specific password.
• Check if the email address and authorization code are correct.
• For enterprise mail, confirm that the administrator has allowed third-party access.

2. [IMAP] EXAMINE Unsafe Login (Common for NetEase Mail)

Cause: NetEase Mail security restrictions. Solution:

• The system will automatically switch to the POP3 protocol.
• Confirm that POP3/SMTP services are enabled in NetEase Mail.
• Use the latest generated 16-digit authorization code.

3. ECONNREFUSED or connection timeout

Cause: Network connection problem. Solution:

• Check the network connection status.
• Confirm that the firewall is not blocking the email ports (25, 465, 587, 993, 995).
• Try a different network environment or VPN.

4. EMAIL_TYPE related errors

Cause: Mismatch between the enterprise email domain name and the server. Solution:

• Set the correct EMAIL_TYPE field for enterprise mail.
• Set Tencent Enterprise Mail to "exmail".
• Set NetEase Enterprise Mail to "netease-enterprise".

Diagnostic Tools

Use the built-in diagnostic commands:

# Test the email configuration
node test-auto-config.js

# Test the EMAIL_TYPE function
node test-email-type.js

# Use the MCP tool to test the connection
# Call test_email_connection in the MCP client

Debugging Tips

1. View detailed logs: The system will automatically output configuration and connection information.
2. Use testing tools: Diagnose problems through test_email_connection.
3. Check the email type: Confirm support using list_supported_providers.
4. Configure step by step: 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 documentation
├── CONFIG_GUIDE.md            # Detailed configuration guide
├── .gitignore                 # Git ignore file
├── 📁 Configuration Templates/
│   ├── mcp-x_config_v2.json      # Universal 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 Instructions

• index.js - The main MCP server program, containing all email functions.
• CONFIG_GUIDE.md - Detailed configuration guide, including various email configuration instructions.
• mcp-x_config_v2.json - Universal configuration template, supporting the EMAIL_TYPE field.
• test-auto-config.js - Script to test the automatic configuration function.
• test-email-type.js - Test script to verify the EMAIL_TYPE field function.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔐 Security Precautions

1. Protect authorization codes: Do not submit authorization codes to the version control system.
2. Use environment variables: It is recommended to use environment variables to store sensitive information.
3. Update regularly: Regularly update authorization codes and check security settings.
4. Permission control: Ensure that only authorized users can access the MCP server.

📞 Technical Support

Documentation Resources

• 📋 CONFIG_GUIDE.md - Complete configuration guide.
• 🔧 Testing tools - Use test-auto-config.js and test-email-type.js.
• 🛠️ Built-in diagnostics - Use the test_email_connection tool.

Official Documentation

• NetEase Mail client settings
• Tencent Enterprise Mail configuration
• QQ Mail help center
• Gmail settings guide

Contribution Guidelines

Welcome to submit issues and pull requests to improve this project!

• 🐛 Report bugs: Please describe the problem and reproduction steps in detail.
• 💡 Feature suggestions: Welcome to propose new email support requirements.
• 📝 Documentation improvement: Help improve the usage documentation.

Project Status

• ✅ Production-ready: Supports 8 major mainstream email service providers.
• 🔄 Continuously updated: Continuously improved based on user feedback.
• 🛡️ Security guaranteed: Supports SSL/TLS encryption and authorization code authentication.

🎉 Quick Test

After configuration, you can test the functions in the MCP client:

Send a test email:

Please send a test email to test@example.com with the subject "MCP Test Email" and the content "Hello from Universal Email MCP!"

Get the email list:

Please get the list of emails from the recent 3 days, limited to 10 emails.

Test the connection:

Please test the email connection status.

If all configurations are correct, all functions should work properly! 🚀