MailWebhook MCP 服务器
基于 Cloudflare Workers 的 MCP (Model Context Protocol) 服务器，为 AI 助手提供邮件发送功能工具。
功能特性
- ✅ 邮件发送: 支持同步/异步发送，支持纯文本和 HTML 格式
- ✅ 模板管理: 查询和使用邮件模板，带智能缓存
- ✅ 状态跟踪: 查询邮件发送状态和历史记录
- ✅ 多传输协议: 支持 HTTP REST、SSE 实时流和 Streamable HTTP
- ✅ MCP 协议兼容: 完全符合 Model Context Protocol 2024-11-05 标准
- ✅ 安全认证: API 令牌认证，CORS 保护，Bearer Token 支持
- ✅ 服务绑定: 使用 Cloudflare 服务绑定实现高性能 Worker 间通信
- ✅ 智能缓存: 基于 Cloudflare Cache API 的模板缓存系统
- ✅ 错误处理: 完善的错误处理和重试机制
- ✅ 类型安全: 完整的 TypeScript 类型定义
快速开始
1. 环境准备
# 克隆项目
git clone
cd mailwebhook-mcp
# 安装依赖
npm install2. 配置通信方式
方式一：服务绑定（推荐）
在 wrangler.toml 中配置服务绑定：
[[services]]
binding = "QQWEBHOOK_SERVICE"
service = "qqwebhook" # 您的 qqwebhook Worker 名称设置可选的认证密钥：
wrangler secret put MCP_API_TOKEN # MCP 服务认证令牌（可选）方式二：HTTP API（备选）
如果无法使用服务绑定，设置传统 HTTP API 配置：
# qqwebhook API 配置
wrangler secret put QQWEBHOOK_API_URL # qqwebhook API 地址
wrangler secret put QQWEBHOOK_API_TOKEN # qqwebhook API 令牌
# MCP 服务认证（可选）
wrangler secret put MCP_API_TOKEN # MCP 服务认证令牌3. 本地开发
# 启动开发服务器
npm run dev4. 部署
# 部署到默认环境
npm run deploy
# 部署到生产环境
npm run deploy:prodMCP 工具
send_email - 发送邮件
发送邮件（支持同步/异步、模板/自定义内容）
参数：
to(string, 必需): 收件人邮箱subject(string, 可选): 邮件主题body(string, 可选): 邮件正文html(string, 可选): HTML 格式邮件template(string, 可选): 模板名称templateData(object, 可选): 模板变量数据async(boolean, 可选): 是否异步发送priority(string, 可选): 邮件优先级 (low/normal/high)
list_email_templates - 列出邮件模板
获取所有可用的邮件模板列表
get_email_template - 获取模板详情
获取指定邮件模板的详细信息
参数：
name(string, 必需): 模板名称
get_email_status - 查询邮件状态
查询指定邮件的发送状态
参数：
messageId(string, 必需): 邮件消息ID
MCP 传输协议
本服务器支持多种 MCP 传输协议，可根据需要选择最适合的方式：
🔥 推荐：Streamable HTTP（最稳定）
最符合 MCP 2024-11-05 标准，支持批量请求和双向通信
# 初始化连接
curl -X POST "https://your-domain.com/mcp/v1" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"Client","version":"1.0"}}}'
# 获取工具列表
curl -X POST "https://your-domain.com/mcp/v1" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":"2","method":"tools/list"}'
# 调用工具
curl -X POST "https://your-domain.com/mcp/v1" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"send_email","arguments":{"to":"test@example.com","subject":"Test"}}}'📡 SSE 实时流传输
适合需要实时通信的 MCP 客户端，双端点架构
# 1. 建立 SSE 连接（获取会话ID）
curl "https://your-domain.com/mcp/sse?token=YOUR_TOKEN" \
-H "Accept: text/event-stream"
# 返回: event: endpoint\ndata: /mcp/sse/message?sessionId=xxx
# 2. 发送消息到会话端点
curl -X POST "https://your-domain.com/mcp/sse/message?sessionId=SESSION_ID" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}'🔧 传统 HTTP 端点（兼容性）
向后兼容的独立端点
# MCP 初始化
curl -X POST "https://your-domain.com/mcp/initialize" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json"
# 获取工具列表
curl -X GET "https://your-domain.com/mcp/tools" \
-H "Authorization: Bearer YOUR_TOKEN"
# 调用工具
curl -X POST "https://your-domain.com/mcp/tools/call" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"params":{"name":"send_email","arguments":{"to":"test@example.com","subject":"Test"}}}'MCP 客户端配置
HTTP 模式配置（推荐）
{
"mcpServers": {
"mailwebhook-mcp": {
"transport": {
"type": "http",
"url": "https://your-domain.com/mcp/v1"
},
"auth": {
"type": "bearer",
"token": "YOUR_API_TOKEN"
},
"description": "邮件发送 MCP 服务器"
}
}
}SSE 模式配置
{
"mcpServers": {
"mailwebhook-mcp-sse": {
"transport": {
"type": "sse",
"url": "https://your-domain.com/mcp/sse?token=YOUR_API_TOKEN"
},
"description": "邮件发送 MCP 服务器 (SSE模式)"
}
}
}API 端点参考
核心 MCP 端点
POST/GET /mcp/v1- Streamable HTTP 端点（推荐）GET /mcp/sse- SSE 连接端点POST /mcp/sse/message- SSE 消息端点POST /mcp/initialize- MCP 初始化（兼容性）GET /mcp/tools- 获取工具列表（兼容性）POST /mcp/tools/call- 调用工具（兼容性）
系统端点
GET /health- 健康检查GET /- API 信息和端点列表
管理端点（需认证）
GET /admin/info- 系统信息和配置状态GET /admin/mcp/stats- MCP 传输协议统计信息POST /admin/cache/warmup- 预热模板缓存DELETE /admin/cache/templates- 清除模板缓存
安全监控端点（需认证）
GET /admin/security/stats- 安全统计和状态报告GET /admin/security/blocked- 查看被速率限制阻止的客户端POST /admin/security/reset-rate-limit- 重置特定客户端的速率限制POST /admin/security/reset-all-rate-limits- 重置所有客户端的速率限制GET /admin/security/health- 安全系统健康检查
安全配置
认证（强制要求）
⚠️ 重要变更：MCP_API_TOKEN 现在是强制要求的，服务器启动时会验证其存在。
认证方式：
- 请求头：
Authorization: Bearer - 查询参数：
?token=
令牌要求：
- 最少 32 个字符
- 包含大写字母、小写字母、数字和特殊字符中的至少三种
- 避免使用常见的弱令牌模式
CORS
配置 CORS_ORIGINS 环境变量：
*- 允许所有来源（开发环境）https://example.com,https://app.example.com- 允许特定域名
安全特性
- ✅ 强制 API 令牌认证：所有受保护端点必需认证
- ✅ 多层速率限制：不同端点有不同的限制阈值
- ✅ 智能客户端识别：基于 IP 地址进行追踪
- ✅ 安全配置验证：启动时检查安全配置完整性
- ✅ 实时安全监控：提供安全状态和被阻止客户端的监控
- ✅ 请求体大小限制：防止过大载荷攻击（1MB）
- ✅ 全面安全响应头：包括 CSP、HSTS 等
- ✅ 输入验证和清理：防止注入攻击
- ✅ 错误信息安全处理：不泄露敏感信息
部署配置
wrangler.toml 示例
name = "mailwebhook-mcp"
main = "src/index.ts"
compatibility_date = "2024-10-02"
# 自定义域名路由
routes = [
{ pattern = "mailwebhook-mcp.finbase.win/*", zone_name = "finbase.win" }
]
# 服务绑定（推荐）
[[services]]
binding = "QQWEBHOOK_SERVICE"
service = "qqwebhook" # qqwebhook Worker 名称
# 环境变量
[vars]
MCP_SERVER_NAME = "QQ Webhook MCP Server"
MCP_SERVER_VERSION = "1.0.0"
CORS_ORIGINS = "*"
CACHE_ENABLED = "true"
CACHE_TTL = "3600"
# 安全配置
RATE_LIMIT_ENABLED = "true"
RATE_LIMIT_WINDOW = "60000"
RATE_LIMIT_MAX_REQUESTS = "60"
AUTH_REQUIRED = "true"
# 生产环境配置
[env.production]
name = "mailwebhook-mcp-prod"
routes = [
{ pattern = "mailwebhook-mcp-prod.finbase.win/*", zone_name = "finbase.win" }
]
[[env.production.services]]
binding = "QQWEBHOOK_SERVICE"
service = "qqwebhook-prod"环境变量
服务绑定配置（推荐）：
QQWEBHOOK_SERVICE- qqwebhook Worker 的服务绑定（在 wrangler.toml 中配置）
缓存配置：
CACHE_ENABLED- 是否启用缓存（默认："true"）CACHE_TTL- 缓存生存时间，秒（默认："3600"）
安全配置（必需）：
MCP_API_TOKEN- MCP 服务器的认证令牌（强制要求）
速率限制配置：
RATE_LIMIT_ENABLED- 是否启用速率限制（默认："true"）RATE_LIMIT_WINDOW- 限制窗口时间，毫秒（默认："60000"）RATE_LIMIT_MAX_REQUESTS- 窗口期内最大请求数（默认："60"）AUTH_REQUIRED- 是否强制认证（默认："true"）
可选配置：
MCP_SERVER_NAME- 服务器名称（默认："QQ Webhook MCP Server"）MCP_SERVER_VERSION- 服务器版本（默认："1.0.0"）CORS_ORIGINS- 允许的跨域来源
备选 HTTP API 配置：
QQWEBHOOK_API_URL- qqwebhook 邮件服务的 API 地址QQWEBHOOK_API_TOKEN- qqwebhook 服务的认证令牌
开发
项目结构
src/
├── handlers/ # MCP 协议处理
├── tools/ # MCP 工具实现
├── middleware/ # 安全中间件
├── utils/ # 工具函数
├── types/ # TypeScript 类型
└── index.ts # 主入口文件代码规范
- 使用 TypeScript 进行类型检查
- 使用 ESLint 进行代码检查
- 遵循项目内的命名约定
- 所有 API 调用需要错误处理
测试
代码检查和构建测试
# 类型检查
npm run type-check
# 代码检查
npm run lint
# 测试部署
npm run dev功能测试
使用 Python 测试脚本（推荐）
本项目包含完整的 Python 测试脚本，用于验证 MCP 服务和 qqwebhook 服务的中文邮件处理功能。
- 配置测试环境：
# 安装测试依赖
pip install requests python-dotenv
# 复制配置模板
cp .env.example .env
# 编辑 .env 文件，填入您的配置- 配置 .env 文件：
# 必需配置
TEST_EMAIL=your_test_email@example.com
MCP_API_TOKEN=your_mcp_token_here
QQWEBHOOK_API_TOKEN=your_qqwebhook_token_here
# 可选配置
DEBUG_VERBOSE=true
SAVE_TEST_RESULTS=true- 运行测试：
# 运行完整测试套件
python test_encoding_new.py
# 或使用旧版简化脚本
python test_encoding.py测试功能：
- ✅ 编码分析：分析 UTF-8 编码处理
- ✅ MCP 工具列表：验证所有 MCP 工具可用性
- ✅ 直接 qqwebhook 测试：验证后端服务正常
- ✅ MCP 服务测试：验证通过 MCP 发送邮件
- ✅ 中文字符测试：确保中文邮件正确显示
- ✅ 结果保存：可选择保存测试结果到 JSON 文件
使用 curl 测试（基础测试）
# 健康检查
curl -X GET https://mailwebhook-mcp.finbase.win/health
# 获取工具列表
curl -X GET https://mailwebhook-mcp.finbase.win/mcp/tools \
-H "Authorization: Bearer your-token"
# 发送测试邮件
curl -X POST https://mailwebhook-mcp.finbase.win/mcp/tools/call \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d '{
"params": {
"name": "send_email",
"arguments": {
"to": "test@example.com",
"subject": "测试邮件",
"body": "这是一封测试邮件"
}
}
}'注意事项：
- Windows 用户使用 curl 可能遇到中文编码问题，建议使用 Python 脚本
- Python 脚本正确处理 UTF-8 编码，确保中文邮件显示正常
- 测试前请确保已正确配置 API 令牌和邮箱地址
故障排除
常见问题
- 认证失败 - 检查
MCP_API_TOKEN配置 - CORS 错误 - 检查
CORS_ORIGINS配置 - 邮件发送失败 - 检查 qqwebhook API 配置和网络连接
调试
# 查看实时日志
wrangler tail
# 检查部署状态
wrangler deployments list许可证
MIT License