📧 通用邮箱 MCP Server
一个让AI轻松接管邮箱的通用MCP服务器，基于 Model Context Protocol (MCP) 构建，支持在 MCP-X、Claude Desktop 等 MCP 客户端中使用。
支持多种邮箱服务商自动配置：QQ邮箱、163邮箱、Gmail、Outlook、腾讯企业邮箱、网易企业邮箱、阿里云邮箱、新浪邮箱、搜狐邮箱等。
📦 快速安装
# npm 安装
npm install -g mcp-email
# 使用 npx 运行（推荐）
npx mcp-email
✨ 功能特性
- 📤 邮件发送: 支持发送HTML和纯文本邮件
- 👥 多收件人: 支持多个收件人、抄送、密送
- 📎 附件支持: 支持文件附件和Base64编码内容
- 🔧 动态配置: 支持运行时配置邮箱服务器
- 🔍 连接测试: 内置SMTP服务器连接测试
- 🛡️ 安全认证: 支持微信企业邮箱授权码认证
- ⚡ 高性能: 优化的连接超时和重试机制
📚 详细配置指南
项目提供了详细的配置指南，包含各大邮箱服务商的配置说明：
📖 CONFIG_GUIDE.md - 完整配置指南，包含：
- 📧 163邮箱详细配置教程
- 🏢 微信企业邮箱配置指南
- 🌐 QQ邮箱、Gmail等主流邮箱配置
- 🛠️ 故障排除和常见问题解决
📋 系统要求
- Node.js 16.x 或更高版本
- 邮箱账号
- MCP 客户端 (如 Claude Desktop)
🚀 快速开始
方式一：直接使用npm包（推荐）
1. 安装npm包
# 全局安装
npm install -g mcp-email
# 或本地安装
npm install mcp-email
2. 在MCP客户端中配置
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"
}
}
}
}
方式二：从源码安装
1. 克隆项目
git clone https://github.com/TimeCyber/email-mcp.git
cd email-mcp
2. 安装依赖
npm install
3. 配置 MCP 客户端（源码安装）
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"
}
}
}
}
企业邮箱配置：
{
"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. 测试配置
# 测试邮件配置是否成功
node test-auto-config.js
📧 邮箱配置指南
获取授权码
不同邮箱的授权码获取方式：
腾讯企业邮箱：
- 访问 企业邮箱管理后台
- 进入 "设置" → "账户" → "客户端专用密码"
- 生成 客户端专用密码 (授权码)
- 进入 "设置" → "收发信设置" → "设置方法"
- 开启 "POP/IMAP/SMTP服务"
QQ邮箱：
- 登录QQ邮箱，进入**"设置"** → "账户"
- 开启**"POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务"**
- 生成授权码
163邮箱：
- 登录163邮箱，进入**"设置"** → "POP3/SMTP/IMAP"
- 开启**"POP3/SMTP/IMAP服务"**
- 设置客户端授权密码
💡 关键提示:
- 企业邮箱必须设置
EMAIL_TYPE字段！ - 个人邮箱可以使用
EMAIL_TYPE: "auto"自动识别
📖 CONFIG_GUIDE.md - 完整配置指南，包含所有邮箱类型详细说明
🔧 MCP 工具说明
1. send_email - 发送邮件
发送邮件，支持多种格式和收件人。
参数
to(必需): 收件人邮箱地址数组subject(必需): 邮件主题text(必需): 纯文本邮件内容cc(可选): 抄送邮箱地址数组bcc(可选): 密送邮箱地址数组html(可选): HTML格式邮件内容attachments(可选): 附件数组
使用示例
基本邮件发送：
{
"to": ["recipient@example.com"],
"subject": "测试邮件",
"text": "这是一封测试邮件"
}
带抄送和HTML内容：
{
"to": ["recipient1@example.com", "recipient2@example.com"],
"cc": ["manager@example.com"],
"subject": "项目报告",
"text": "请查看项目报告",
"html": "<h1>项目报告</h1><p>项目进展顺利。</p>"
}
带附件的邮件：
{
"to": ["recipient@example.com"],
"subject": "带附件的邮件",
"text": "请查看附件",
"attachments": [
{
"filename": "report.pdf",
"path": "C:\\path\\to\\report.pdf"
},
{
"filename": "data.txt",
"content": "SGVsbG8gV29ybGQ="
}
]
}
2. get_recent_emails - 获取最近邮件
获取最近几天的邮件列表，自动选择最佳协议（IMAP/POP3）。
参数
limit(可选): 返回邮件数量限制，默认20days(可选): 获取最近几天的邮件，默认3天
使用示例
{
"limit": 10,
"days": 7
}
3. get_email_content - 获取邮件内容
获取指定邮件的详细内容。
参数
uid(必需): 邮件唯一标识符（从邮件列表中获取）
使用示例
{
"uid": "12345"
}
4. setup_email_account - 设置邮箱账号
自动识别邮箱类型并配置服务器，支持8大邮箱服务商。
参数
email(必需): 邮箱地址password(必需): 邮箱密码或授权码provider(可选): 邮箱提供商（手动指定，用于企业邮箱）
支持的邮箱类型
qq- QQ邮箱163- 网易邮箱gmail- Gmailoutlook- Outlook/Hotmailexmail- 腾讯企业邮箱netease-enterprise- 网易企业邮箱aliyun- 阿里云邮箱sina- 新浪邮箱sohu- 搜狐邮箱
使用示例
个人邮箱（自动识别）：
{
"email": "user@qq.com",
"password": "your-auth-code"
}
企业邮箱（手动指定）：
{
"email": "user@company.com",
"password": "your-enterprise-auth-code",
"provider": "exmail"
}
5. list_supported_providers - 列出支持的邮箱
查看所有支持的邮箱服务商及其配置信息。
参数
无需参数
使用示例
{}
6. configure_email_server - 手动配置服务器
手动配置邮箱服务器设置（高级用户使用）。
参数
user(必需): 邮箱账号password(必需): 邮箱密码或授权码smtpHost(可选): SMTP服务器地址smtpPort(可选): SMTP端口smtpSecure(可选): 是否使用SSLimapHost(可选): IMAP服务器地址imapPort(可选): IMAP端口imapSecure(可选): 是否使用SSL
使用示例
{
"user": "your-email@domain.com",
"password": "your-password",
"smtpHost": "smtp.domain.com",
"smtpPort": 465,
"smtpSecure": true
}
7. test_email_connection - 测试连接
测试邮箱服务器连接状态。
参数
testType(可选): 测试类型smtp- 仅测试发送服务器imap- 仅测试接收服务器both- 测试全部（默认）
使用示例
{
"testType": "smtp"
}
📊 支持的邮箱服务商
主流邮箱服务器配置
| 邮箱类型 | SMTP服务器 | SMTP端口 | IMAP服务器 | IMAP端口 | 推荐协议 |
|---|---|---|---|---|---|
| QQ邮箱 | smtp.qq.com | 587 | imap.qq.com | 993 | IMAP |
| 网易邮箱 | 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 |
| 腾讯企业邮箱 | smtp.exmail.qq.com | 465 | imap.exmail.qq.com | 993 | IMAP |
| 阿里云邮箱 | smtp.mxhichina.com | 465 | imap.mxhichina.com | 993 | IMAP |
*网易邮箱（163/126/yeah）自动使用POP3协议以避免"Unsafe Login"错误
Gmail特殊说明: 从2025年5月1日起，Google Workspace账号不再支持"less secure apps"，必须使用OAuth认证。个人Gmail需要使用应用专用密码。详见配置指南。*
🔧 自动配置特性
- ✅ 智能识别: 根据邮箱域名自动选择服务器配置
- ✅ 协议优化: 163邮箱自动使用POP3，其他使用IMAP
- ✅ 企业邮箱: 支持通过
EMAIL_TYPE字段手动指定 - ✅ 错误处理: IMAP失败时自动尝试POP3协议
🔍 故障排除
常见错误和解决方案
1. 535 Error: authentication failed
原因: 认证失败 解决方案:
- 确认已在邮箱设置中开启SMTP/IMAP/POP3服务
- 重新生成授权码或应用专用密码
- 检查邮箱地址和授权码是否正确
- 对于企业邮箱，确认管理员已允许第三方访问
2. [IMAP] EXAMINE Unsafe Login (网易邮箱常见)
原因: 网易邮箱安全限制 解决方案:
- 系统会自动切换到POP3协议
- 确认已在网易邮箱中开启POP3/SMTP服务
- 使用最新生成的16位授权码
3. ECONNREFUSED 或连接超时
原因: 网络连接问题 解决方案:
- 检查网络连接状态
- 确认防火墙没有阻挡邮件端口 (25, 465, 587, 993, 995)
- 尝试不同的网络环境或VPN
4. EMAIL_TYPE 相关错误
原因: 企业邮箱域名和服务器不匹配 解决方案:
- 为企业邮箱设置正确的
EMAIL_TYPE字段 - 腾讯企业邮箱设置为
"exmail" - 网易企业邮箱设置为
"netease-enterprise"
📋 诊断工具
使用内置诊断命令：
# 测试邮箱配置
node test-auto-config.js
# 测试EMAIL_TYPE功能
node test-email-type.js
# 使用MCP工具测试连接
# 在MCP客户端中调用 test_email_connection
🔧 调试技巧
- 查看详细日志: 系统会自动输出配置和连接信息
- 使用测试工具: 通过
test_email_connection诊断问题 - 检查邮箱类型: 使用
list_supported_providers确认支持 - 逐步配置: 先使用
setup_email_account自动配置
📁 项目结构
├── index.js # MCP Server主程序
├── package.json # 项目依赖配置
├── README.md # 项目主文档
├── CONFIG_GUIDE.md # 详细配置指南
├── .gitignore # Git忽略文件
├── 📁 配置模板/
│ ├── mcp-x_config_v2.json # 通用配置模板
│ └── mcp-x_config_multi.json # 多账户配置
├── 📁 测试工具/
│ ├── test-auto-config.js # 自动配置测试
│ └── test-email-type.js # EMAIL_TYPE功能测试
└── LICENSE # 开源许可证
🔑 核心文件说明
index.js- 主要的MCP服务器程序，包含所有邮件功能CONFIG_GUIDE.md- 详细的配置指南，包含各种邮箱配置说明mcp-x_config_v2.json- 通用配置模板，支持EMAIL_TYPE字段test-auto-config.js- 测试自动配置功能的脚本test-email-type.js- 验证EMAIL_TYPE字段功能的测试脚本
🔐 安全注意事项
- 保护授权码: 不要将授权码提交到版本控制系统
- 使用环境变量: 推荐使用环境变量存储敏感信息
- 定期更新: 定期更新授权码和检查安全设置
- 权限控制: 确保只有授权用户可以访问MCP服务器
📞 技术支持
📖 文档资源
- 📋 CONFIG_GUIDE.md - 完整配置指南
- 🔧 测试工具 - 使用
test-auto-config.js和test-email-type.js - 🛠️ 内置诊断 - 使用
test_email_connection工具
🌐 官方文档
🤝 贡献指南
欢迎提交 Issue 和 Pull Request 来改进这个项目！
- 🐛 报告Bug: 请详细描述问题和复现步骤
- 💡 功能建议: 欢迎提出新的邮箱支持需求
- 📝 文档改进: 帮助完善使用文档
📊 项目状态
- ✅ 生产就绪: 支持8大主流邮箱服务商
- 🔄 持续更新: 根据用户反馈不断改进
- 🛡️ 安全保障: 支持SSL/TLS加密和授权码认证
📄 许可证
MIT License - 详见 LICENSE 文件
🎉 快速测试
配置完成后，可以在MCP客户端中测试功能：
发送测试邮件：
请发送一封测试邮件到 test@example.com，主题为"MCP测试邮件"，内容为"Hello from Universal Email MCP!"
获取邮件列表：
请获取最近3天的邮件列表，限制10封邮件
测试连接：
请测试邮箱连接状态
如果一切配置正确，所有功能都应该正常工作！🚀