MCP Email Service

一个基于MCP (Model Context Protocol) 的邮件管理服务，支持多邮箱提供商的完整邮件管理功能。目前已完美支持163邮箱，其他邮箱提供商正在开发中。

✨ 核心功能

• 📧 邮件管理: 查看、详情、标记已读、删除、移动到垃圾箱
• 🔄 批量操作: 批量标记已读、批量删除、批量移动到垃圾箱
• 📊 统计信息: 未读邮件数量、邮箱状态检查
• 🔧 技术突破: 解决各种邮箱提供商的技术限制 (如163邮箱IMAP "Unsafe Login")
• 🎯 MCP集成: 完美集成MCP协议客户端，支持10个MCP工具

🚀 快速开始

1. 环境要求

• Python 3.11+
• UV包管理器

2. 安装UV (如果尚未安装)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或使用 Homebrew (macOS)
brew install uv

3. 克隆项目

git clone <your-repo-url>
cd mcp-email-service

4. 项目初始化

# 创建虚拟环境并安装依赖
uv sync

# 验证安装
uv run python --version

5. 邮箱配置

当前支持的邮箱提供商:

• ✅ 163邮箱 - 完全支持
• 🔄 Gmail - 开发中
• 🔄 Outlook - 开发中
• 🔄 QQ邮箱 - 开发中

5.1 配置163邮箱 (当前支持)

1. 登录163邮箱: 访问 https://mail.163.com
2. 进入设置: 点击右上角设置 → POP3/SMTP/IMAP
3. 开启IMAP服务: 开启 IMAP/SMTP 服务
4. 获取授权码: 完成手机验证后获取授权码

⚠️ 重要: 授权码不是邮箱密码！是专门用于第三方客户端的授权码。

5.2 配置环境变量

# 复制配置模板
cp .env.example .env

# 编辑配置文件
# 在 .env 文件中设置：
EMAIL_PROVIDER=163                    # 邮箱提供商 (目前支持: 163)
EMAIL_ADDRESS=your_email@163.com      # 你的邮箱地址
EMAIL_PASSWORD=your_authorization_code  # 163邮箱授权码

注意: 其他邮箱提供商的配置方式正在开发中，敬请期待！

6. 测试运行

# 测试MCP服务
uv run python src/main.py

# 在另一个终端测试功能
uv run python -c "
import asyncio
import sys
sys.path.append('src')
from main import handle_call_tool

async def test():
    result = await handle_call_tool('check_connection', {})
    print(result[0]['text'])

asyncio.run(test())
"

成功显示类似信息表示配置正确：

✅ 连接成功！
📬 总邮件: 1423
🔴 未读邮件: 16

🔧 MCP客户端集成

在MCP客户端配置文件中添加以下配置：

{
    "mcpServers": {
        "mcp-email-service": {
            "command": "/Users/leo/github.com/mcp-email-service/run.sh",
            "args": []
        }
    }
}

启动脚本说明:

• run.sh: 简单的启动脚本，包含以下功能：
  • 自动切换到项目目录
  • 使用UV运行Python服务 (uv run python src/main.py)
  • 确保在正确的环境中启动MCP服务

只需修改配置中的路径为你的实际项目路径，重启MCP客户端即可使用！

📋 可用的MCP工具

基础功能 (4个)

• check_connection - 检查邮箱连接状态
• list_emails - 获取邮件列表 (默认50封)
• get_unread_count - 获取未读邮件数量
• get_email_detail - 获取邮件详细内容

单个操作 (3个)

• mark_email_read - 标记邮件为已读
• delete_email - 永久删除邮件
• move_email_to_trash - 移动邮件到垃圾箱

批量操作 (3个)

• batch_mark_read - 批量标记已读
• batch_delete_emails - 批量删除
• batch_move_to_trash - 批量移动到垃圾箱

💡 使用示例

在MCP客户端中可以这样使用：

# 查看未读邮件数量
get_unread_count

# 获取最新10封邮件
list_emails with limit=10

# 获取所有未读邮件
list_emails with unread_only=true

# 查看特定邮件详情
get_email_detail with email_id="1423"

# 批量标记邮件为已读
batch_mark_read with email_ids=["1423", "1422", "1421"]

# 批量移动到垃圾箱
batch_move_to_trash with email_ids=["1420", "1419"]

🔧 技术特性

核心技术：多提供商适配架构

针对不同邮箱提供商的技术特点，实现相应的解决方案。

163邮箱的IMAP ID解决方案: 通过实现RFC 2971 IMAP ID扩展，完美解决163邮箱的"Unsafe Login"限制：

def send_imap_id(mail):
    """Send IMAP ID to solve 163 email 'Unsafe Login' issue"""
    id_args = [
        "name", "Mozilla Thunderbird",
        "version", "91.0", 
        "vendor", "Mozilla",
        "support-url", "https://support.mozilla.org/"
    ]
    # 在登录前后发送ID信息确保兼容性

特性亮点

• 🛡️ 完善的错误处理和批量操作失败恢复
• 🚀 默认获取50封邮件，提升用户体验
• 🌍 智能MIME解码，支持多语言邮件
• ⚡ 批量操作优化，减少网络连接次数

🐛 常见问题

Q: "❌ 邮箱登录失败"

A: 对于163邮箱，检查以下几点：

1. 确认已开启IMAP服务
2. 使用授权码而非邮箱密码
3. 重新生成授权码
4. 确认邮箱地址正确

对于其他邮箱: 请等待相应提供商的支持更新

Q: "❌ 连接超时"

A: 检查网络连接和防火墙设置

Q: MCP客户端中看不到邮件工具

A:

1. 检查配置文件JSON格式是否正确
2. 确认路径是否正确
3. 重启MCP客户端

🎯 开发路线图

🔄 正在开发

• [ ] Gmail支持 - OAuth2认证和API集成
• [ ] Outlook支持 - Microsoft Graph API集成
• [ ] QQ邮箱支持 - 腾讯邮箱服务集成

📋 计划功能

• [ ] 邮件搜索功能 (按关键词、发件人、日期范围)
• [ ] 邮件发送功能 (支持附件)
• [ ] 邮件文件夹管理 (创建、删除、移动)
• [ ] 邮件附件处理 (下载、预览)
• [ ] 邮件模板系统
• [ ] 邮件规则和过滤器

🚀 长期规划

• [ ] 企业邮箱支持 (Exchange, POP3等)
• [ ] 多账户管理
• [ ] 邮件备份和导出功能

📄 许可证

MIT License

---

注意: 请不要将包含敏感信息的.env文件提交到版本控制系统中。