shield_lock
JinDaGe
Contact
← Back to MCP directory
publicPublicdnsLocal runtime

email-mcp

一个基于Model Context Protocol的通用邮箱管理服务器，支持QQ、163、Gmail等主流邮箱服务商的自动配置，提供邮件发送、接收、附件管理等完整功能。

article

README

🚀 📧 通用邮箱 MCP Server

一个让AI轻松接管邮箱的通用MCP服务器，基于 Model Context Protocol (MCP) 构建，支持在 MCP-X、Claude Desktop 等 MCP 客户端中使用。支持多种邮箱服务商自动配置，如QQ邮箱、163邮箱、Gmail、Outlook、腾讯企业邮箱、网易企业邮箱、阿里云邮箱、新浪邮箱、搜狐邮箱等。

🚀 快速开始

方式一：直接使用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

✨ 主要特性

  • 📤 邮件发送：支持发送HTML和纯文本邮件
  • 👥 多收件人：支持多个收件人、抄送、密送
  • 📎 附件支持：支持文件附件和Base64编码内容
  • 🔧 动态配置：支持运行时配置邮箱服务器
  • 🔍 连接测试：内置SMTP服务器连接测试
  • 🛡️ 安全认证：支持微信企业邮箱授权码认证
  • ⚡ 高性能：优化的连接超时和重试机制

📦 安装指南

# npm 安装
npm install -g mcp-email

# 使用 npx 运行（推荐）
npx mcp-email

💻 使用示例

基础用法

发送邮件

{
  "to": ["recipient@example.com"],
  "subject": "测试邮件",
  "text": "这是一封测试邮件"
}

获取最近邮件

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

获取邮件内容

{
  "uid": "12345"
}

设置邮箱账号

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

列出支持的邮箱

{}

手动配置服务器

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

测试连接

{
  "testType": "smtp"
}

高级用法

带抄送和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="
    }
  ]
}

企业邮箱设置

{
  "email": "user@company.com",
  "password": "your-enterprise-auth-code",
  "provider": "exmail"
}

📚 详细文档

项目提供了详细的配置指南，包含各大邮箱服务商的配置说明： 📖 CONFIG_GUIDE.md - 完整配置指南，包含：

  • 📧 163邮箱详细配置教程
  • 🏢 微信企业邮箱配置指南
  • 🌐 QQ邮箱、Gmail等主流邮箱配置
  • 🛠️ 故障排除和常见问题解决

🔧 技术细节

MCP 工具说明

1. send_email - 发送邮件

发送邮件，支持多种格式和收件人。

  • 参数：
    • to (必需)：收件人邮箱地址数组
    • subject (必需)：邮件主题
    • text (必需)：纯文本邮件内容
    • cc (可选)：抄送邮箱地址数组
    • bcc (可选)：密送邮箱地址数组
    • html (可选)：HTML格式邮件内容
    • attachments (可选)：附件数组

2. get_recent_emails - 获取最近邮件

获取最近几天的邮件列表，自动选择最佳协议（IMAP/POP3）。

  • 参数：
    • limit (可选)：返回邮件数量限制，默认20
    • days (可选)：获取最近几天的邮件，默认3天

3. get_email_content - 获取邮件内容

获取指定邮件的详细内容。

  • 参数：
    • uid (必需)：邮件唯一标识符（从邮件列表中获取）

4. setup_email_account - 设置邮箱账号

自动识别邮箱类型并配置服务器，支持8大邮箱服务商。

  • 参数：
    • email (必需)：邮箱地址
    • password (必需)：邮箱密码或授权码
    • provider (可选)：邮箱提供商（手动指定，用于企业邮箱）
  • 支持的邮箱类型：
    • qq - QQ邮箱
    • 163 - 网易邮箱
    • gmail - Gmail
    • outlook - Outlook/Hotmail
    • exmail - 腾讯企业邮箱
    • netease-enterprise - 网易企业邮箱
    • aliyun - 阿里云邮箱
    • sina - 新浪邮箱
    • sohu - 搜狐邮箱

5. list_supported_providers - 列出支持的邮箱

查看所有支持的邮箱服务商及其配置信息。

  • 参数：无需参数

6. configure_email_server - 手动配置服务器

手动配置邮箱服务器设置（高级用户使用）。

  • 参数：
    • user (必需)：邮箱账号
    • password (必需)：邮箱密码或授权码
    • smtpHost (可选)：SMTP服务器地址
    • smtpPort (可选)：SMTP端口
    • smtpSecure (可选)：是否使用SSL
    • imapHost (可选)：IMAP服务器地址
    • imapPort (可选)：IMAP端口
    • imapSecure (可选)：是否使用SSL

7. test_email_connection - 测试连接

测试邮箱服务器连接状态。

  • 参数：
    • testType (可选)：测试类型
      • smtp - 仅测试发送服务器
      • imap - 仅测试接收服务器
      • both - 测试全部（默认）

支持的邮箱服务商

主流邮箱服务器配置

| 邮箱类型 | 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

调试技巧

  1. 查看详细日志：系统会自动输出配置和连接信息
  2. 使用测试工具：通过 test_email_connection 诊断问题
  3. 检查邮箱类型：使用 list_supported_providers 确认支持
  4. 逐步配置：先使用 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字段功能的测试脚本

📦 邮箱配置指南

获取授权码

腾讯企业邮箱

  1. 访问 企业邮箱管理后台
  2. 进入 "设置" → "账户" → "客户端专用密码"
  3. 生成 客户端专用密码 (授权码)
  4. 进入 "设置" → "收发信设置" → "设置方法"
  5. 开启 "POP/IMAP/SMTP服务"

QQ邮箱

  1. 登录QQ邮箱，进入**"设置"** → "账户"
  2. 开启**"POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务"**
  3. 生成授权码

163邮箱

  1. 登录163邮箱，进入**"设置"** → "POP3/SMTP/IMAP"
  2. 开启**"POP3/SMTP/IMAP服务"**
  3. 设置客户端授权密码

💡 使用建议

  • 企业邮箱必须设置 EMAIL_TYPE 字段！
  • 个人邮箱可以使用 EMAIL_TYPE: "auto" 自动识别

📖 CONFIG_GUIDE.md - 完整配置指南，包含所有邮箱类型详细说明

🔐 安全注意事项

  1. 保护授权码：不要将授权码提交到版本控制系统
  2. 使用环境变量：推荐使用环境变量存储敏感信息
  3. 定期更新：定期更新授权码和检查安全设置
  4. 权限控制：确保只有授权用户可以访问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封邮件

测试连接：

请测试邮箱连接状态

如果一切配置正确，所有功能都应该正常工作！🚀

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client