Imap Email MCP

IMAP电子邮件MCP服务器

一种模型上下文协议（MCP）服务器，使AI助手能够通过IMAP/SMTP获取、读取、汇总和发送电子邮件。该服务器通过MCP协议公开了三个主要工具，用于OpenAI的Responses API。

特性

• 在指定时间范围内从IMAP服务器获取电子邮件
• 无需人工智能处理即可阅读完整的电子邮件内容
• 使用GPT-4o-mini进行人工智能电子邮件摘要，重点关注关键点、发件人和行动项
• 通过SMTP发送电子邮件，支持CC、BCC和HTML内容
• 支持SSE的HTTP MCP协议
• OpenAI Builder MCP兼容性
• Ngrok集成，用于远程访问本地运行的服务器

建筑

graph TD
    A[OpenAI Responses API] -->|MCP Protocol| B[MCP SSE Server]
    B -->|ngrok tunnel| C[Public URL]
    B -->|Fetch Emails| D[IMAP Server]
    B -->|Send Emails| E[SMTP Server]
    B -->|Summarize| F[OpenAI API]
    
    subgraph "Your Server"
        B
    end
    
    subgraph "Email Provider"
        D
        E
    end

依赖项

graph LR
    A[mcp_sse_server.py] --> B[FastAPI/Uvicorn]
    A --> C[IMAP/SMTP Libraries]
    A --> D[OpenAI Python SDK]
    A --> E[python-dotenv]
    A --> F[sse-starlette]
    
    G[start_server.sh] --> A
    H[start_ngrok.sh] --> I[ngrok]
    I --> A

安装

先决条件

• Python 3.8或更高版本
• 具有自定义域的ngrok帐户（供公众访问）
• IMAP/SMTP电子邮件帐户凭据

步骤1：克隆或导航到目录

例如

cd /Users/frank/projects/ai-agent/imap-email-mcp

第二步：创建虚拟环境

python3 -m venv venv
source venv/bin/activate

步骤3：安装Python依赖项

pip install -r requirements.txt

要求包括：

• python-dotenv -环境变量管理
• openai -OpenAI API客户端
• fastapi -Web框架
• uvicorn -ASGI服务器
• sse-starlette -服务器发送事件支持

步骤4：配置环境变量

创建一个 .env 项目目录中的文件：

# OpenAI Configuration (optional)
OPENAI_API_KEY=your_openai_api_key_here

# IMAP Configuration
IMAP_HOST=imap.yourdomain.com
IMAP_USER=your_email@yourdomain.com
IMAP_PASS=your_email_password

# SMTP Configuration
SMTP_HOST=smtp.yourdomain.com
SMTP_PORT=465
EMAIL_FROM_NAME=Your Name

# Server Configuration
FLASK_PORT=5001
FLASK_HOST=0.0.0.0

# Authentication (optional but recommended)
MCP_API_KEY=your_generated_api_key_here

生成API密钥：

为了安全起见，请生成一个安全的API密钥：

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

将生成的密钥添加到您的 .env 文件为 MCP_API_KEY.

步骤5：安装ngrok（用于远程访问）

1. 下载ngrokhttps://ngrok.com/download
2. 在ngrok控制面板中设置自定义域名（需要付费计划）
3. 使启动脚本可执行：

chmod +x start_ngrok.sh
chmod +x start_server.sh

用法

启动MCP服务器

在本地启动服务器：

./start_server.sh

服务器将于启动 http://localhost:5001

通过ngrok曝光

在单独的终端中，使用您的自定义域名启动ngrok隧道：

./start_ngrok.sh yourdomain.ngrok.dev

例子：

./start_ngrok.sh frankimap.ngrok.dev

您的MCP服务器现在可以在以下网址访问 https://yourdomain.ngrok.dev/sse

MCP工具

服务器通过MCP协议公开了三个工具：

1.邮件摘要

提取并汇总指定时间范围内的电子邮件。

输入架构：

{
  "start_iso": "2024-11-25T00:00:00Z",
  "end_iso": "2024-11-25T23:59:59Z"
}

示例用例： “显示今天的电子邮件”或“总结上周的电子邮件”

参数：

• start_iso （必填）：ISO 8601格式的开始时间，后缀为Z
• end_iso （必填）：ISO 8601格式的结束时间，后缀为Z

答复： 返回该时间范围内所有电子邮件的摘要，包括：

• 找到的电子邮件数量
• 人工智能生成的电子邮件内容摘要
• 个人电子邮件详细信息（发件人、主题、日期、预览）

2.阅读电子邮件

从指定时间范围内获取并返回完整的电子邮件内容，无需人工智能摘要。

输入架构：

{
  "start_iso": "2024-11-25T00:00:00Z",
  "end_iso": "2024-11-25T23:59:59Z"
}

示例用例： “阅读今天早上的所有电子邮件”或“显示昨天收到的电子邮件的全部内容”

参数：

• start_iso （必填）：ISO 8601格式的开始时间，后缀为Z
• end_iso （必填）：ISO 8601格式的结束时间，后缀为Z

答复： 返回时间范围内的完整电子邮件数据，包括：

• 找到的电子邮件数量
• 个人电子邮件详细信息（发件人、主题、日期、正文预览）
• 无人工智能摘要-仅原始电子邮件数据

3.发送电子邮件

向一个或多个收件人发送电子邮件。

输入架构：

{
  "to": ["recipient@example.com"],
  "subject": "Hello from MCP",
  "body": "This is the email content",
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"],
  "body_type": "plain"
}

示例用例： “发送电子邮件至john@example.com主题为“明天开会”，并告诉他上午10点的会议”

参数：

• to （必填）：收件人电子邮件地址数组
• subject （必填）：电子邮件主题行
• body （必填）：电子邮件正文内容
• cc （可选）：CC收件人数组
• bcc （可选）：BCC收件人数组
• body_type （可选）：“plain”或“html”（默认：“plaine”）

答复： 返回发送状态及详细信息：

• 状态（成功/错误）
• 收件人（收件人、抄送、密件抄送）
• 主题
• 时间戳

电子邮件摘要的工作原理

这 summarize_emails 该工具使用多步骤过程来提供智能电子邮件摘要：

第一步：电子邮件检索

• 使用提供的凭据连接到IMAP服务器
• 搜索指定日期范围内的电子邮件
• 提取关键元数据：发件人、主题、日期和正文预览

第二步：内容格式化

所有检索到的电子邮件都格式化为结构化文本块：

From: sender@example.com
Subject: Email Subject
Date: 2024-11-25 10:30:00

[Body preview text]

---

[Next email...]

第三步：人工智能分析

格式化的电子邮件被发送到OpenAI的GPT-4o-mini模型，其中包含：

• 系统提示：指示AI充当电子邮件摘要助手
• 重点领域：关键点、发送者和行动项
• 参数:

- 型号： gpt-4o-mini - 温度： 0.7 （平衡创造力和一致性） - 最大令牌数： 500 （简明摘要）

步骤4：结构化响应

返回一个JSON对象，其中包含：

• 查询的时间范围
• 电子邮件总数
• 个人电子邮件详细信息（完整列表）
• 人工智能生成的摘要，突出显示重要信息

这种方法可确保您获得快速概述（人工智能摘要）和详细信息（个人电子邮件），以便在需要时进行更深入的分析。

认证

服务器支持 承载令牌身份验证 以保护您的MCP端点。

设置身份验证

1. 生成安全的API密钥：

   python3 -c "import secrets; print(secrets.token_urlsafe(32))"

1. 添加到 .env 文件：

   MCP_API_KEY=your_generated_api_key_here

1. 重新启动服务器：

   ./start_server.sh

您应该看到： 🔒 Authentication: ENABLED

使用身份验证

使用OpenAI Builder：

• 将身份验证方法设置为： “访问令牌/API密钥”
• 粘贴您的 MCP_API_KEY API键字段中的值

卷曲：

# Without auth (will fail if MCP_API_KEY is set)
curl https://yourdomain.ngrok.dev/sse

# With auth (will succeed)
curl -H "Authorization: Bearer YOUR_API_KEY" https://yourdomain.ngrok.dev/sse

安全说明：

• ✅ 使用Bearer令牌身份验证进行生产
• 🔒 保持你的 MCP_API_KEY 秘密
• 🔄 定期旋转钥匙
• 📝 永不承诺 .env 转git
• ⚠️ 如果 MCP_API_KEY 未设置，身份验证已禁用（仅用于开发）

OpenAI集成

要将此MCP服务器与OpenAI的Responses API一起使用，请执行以下操作：

1. 启动MCP服务器和ngrok隧道
2. 使用MCP端点配置OpenAI助手：

{
  "type": "mcp",
  "url": "https://yourdomain.ngrok.dev/sse",
  "auth": {
    "type": "bearer",
    "token": "your_mcp_api_key"
  }
}

1. AI助手现在可以根据用户请求自动调用电子邮件工具

API终点

• GET / -健康检查和服务信息
• GET /sse -MCP协议信息
• POST /sse -MCP协议端点（JSON-RPC 2.0）
• POST /tool/summarize_emails -用于电子邮件摘要的直接REST端点

故障排除

服务器无法启动：

• 检查端口5001是否可用
• 验证是否在中设置了所有必需的环境变量 .env
• 确保安装了Python依赖项

ngrok连接失败：

• 验证您的ngrok身份验证令牌是否已配置
• 检查您的自定义域是否在ngrok仪表板中正确设置
• 自定义域名需要付费的ngrok计划

电子邮件操作失败：

• 验证IMAP/SMTP凭据是否正确
• 检查您的电子邮件提供商是否允许IMAP/SMTP访问
• 一些提供商需要特定于应用程序的密码

OpenAI摘要失败：

• 验证您的OpenAI API密钥是否有效并具有信用

身份验证错误（401未经授权）：

• 验证 MCP_API_KEY 设置在您的 .env 文件
• 检查授权标头是否包括 Bearer 前缀
• 确保API键完全匹配（没有额外的空格或引号）
• 更新后重新启动服务器 .env 文件
• 检查API密钥是否可以访问所需的模型

安全说明

• 永远不要承诺你的 .env 文件到版本控制
• 尽可能为电子邮件帐户使用特定于应用程序的密码
• 确保OpenAI API密钥的安全
• 考虑将ngrok的身份验证功能用于生产用途

支持

有关电子邮件格式要求的其他文档，请参阅 SEND_EMAIL_FORMAT.md