Mail MCP (Python + modelcontextprotocol)

这是一个邮件助手 MCP 服务，基于 Python 和官方 MCP Python SDK（mcp 包），并真实对接 Outlook（Microsoft Graph）。

当前版本实现：

• MCP 服务入口

• Outlook 邮箱读写（Microsoft Graph）

• 常见邮件助手基础工具（列目录、读邮件、搜索、写草稿、发草稿、撤销草稿）

1. 环境准备

要求：

• Python 3.10+

安装：

python -m venv .venv
.venv\\Scripts\\activate
pip install -U pip
pip install -e .

Related MCP server: Gmail AutoAuth MCP Server

2. 启动服务

mail-mcp

或者：

python -m mail_mcp.server

服务进程本身默认使用 HTTP（streamable-http），推荐通过反向代理提供 HTTPS。

2.0 通过 Docker 部署到 Azure App Service

仓库已提供 Dockerfile 和 .dockerignore。

服务在容器内默认监听：

• Host: 0.0.0.0

• Port: 80（也兼容 App Service 注入的 PORT）

• MCP Path: /mcp

推荐流程：

1. 使用 ACR 云端构建镜像（无需本地 Docker）

az acr build \
  --registry <acr-name> \
  --image mail-mcp:latest \
  .

2. （可选）查看 ACR 中镜像标签

az acr repository show-tags \
  --name <acr-name> \
  --repository mail-mcp \
  --output table

3. 在 App Service 使用该镜像（Web App for Containers）

• Image source: ACR

• Image: <acr-name>.azurecr.io/mail-mcp:latest

• Container port: 80

• Health check path: /healthz

4. MCP 客户端连接地址

• https://<app-name>.azurewebsites.net/mcp

5. 部署后验证

• https://<app-name>.azurewebsites.net/

• https://<app-name>.azurewebsites.net/healthz

2.1 Outlook 鉴权配置

服务会按以下优先级获取 Bearer Token：

1. MCP 请求头中的 Authorization: Bearer <token>（推荐）

2. 环境变量 OUTLOOK_ACCESS_TOKEN（调试兜底，Graph 与 EWS 均适用）

可选环境变量：

• MAIL_MCP_BACKEND（默认 graph，可选 graph / ews；决定使用 Microsoft Graph 还是 Exchange Server EWS）

• GRAPH_BASE_URL（默认 https://graph.microsoft.com/v1.0）

• DELEGATED_TOKEN_LOG_MODE（默认 masked，可选 masked / full / none）

• DELEGATED_TOKEN_CACHE_TTL_SECONDS（默认 300，token 校验结果缓存秒数）

• MCP_EXPOSE_AGENTS_MD（默认 false，设置为 true 后对外暴露 mailbox_get_agents_md() 工具，返回仓库根目录 AGENTS.md 内容）

后端切换示例：

# 使用 Microsoft Graph（默认）
MAIL_MCP_BACKEND=graph

# 使用 Exchange Server EWS
MAIL_MCP_BACKEND=ews

Exchange Server EWS 后端专用环境变量（仅在 MAIL_MCP_BACKEND=ews 时生效；此模式不再兼容用户名/密码认证）：

# 选择 EWS 后端
MAIL_MCP_BACKEND=ews

# Exchange Server EWS 终结点（例如 EWS 地址）
EXCHANGE_SERVER_URL=https://exchange.example.com/EWS/Exchange.asmx

# Entra ID / OAuth 2.0 认证信息
EXCHANGE_SERVER_CLIENT_ID=<app-registration-client-id>
EXCHANGE_SERVER_CLIENT_SECRET=<app-registration-client-secret>
EXCHANGE_SERVER_TENANT_ID=<tenant-id>

# 可选：Mailbox 时区，默认 UTC
EXCHANGE_SERVER_TIME_ZONE=Asia/Shanghai

注意：

• 该模式已改为 bearer token 认证，不再接受 EXCHANGE_SERVER_USERNAME / EXCHANGE_SERVER_PASSWORD。

• EWS 也支持统一的 token 解析顺序：当前请求头中的 Authorization: Bearer <token> 优先，未提供时回退到 OUTLOOK_ACCESS_TOKEN。

• EWS 仅从当前登录用户的 bearer token 中解析邮箱，不支持指定邮箱/共享邮箱。

• EXCHANGE_SERVER_URL 必须指向实际的 EWS/Exchange 端点，不要只填域名。

2.1.1 配置分层（推荐：非敏感入库，敏感留在 App Service）

服务启动时按以下优先级加载配置（高 -> 低）：

1. 进程环境变量（例如 Azure App Service 的 App Settings）

2. 仓库根目录 .env（本地私有，不入库）

3. 当 APP_ENV 已设置时：.env.<APP_ENV>；否则：.env.prod

说明：

• 项目已支持将 .env.prod 提交到 Git（用于非敏感默认值）。

• 机密信息仍应只放在 App Service App Settings（或 Key Vault），不要写入 .env.prod。

建议放入 .env.prod 的示例（非敏感）：

• MCP_HOST / MCP_PORT / MCP_PATH

• MAIL_MCP_BACKEND（graph 或 ews）

• GRAPH_BASE_URL

• DELEGATED_TOKEN_LOG_MODE

• DELEGATED_TOKEN_CACHE_TTL_SECONDS

• MCP_EXPOSE_AGENTS_MD

建议仅放在 App Service 的示例（敏感/租户强绑定）：

• AZURE_CLIENT_SECRET

• MCP_OAUTH_CLIENT_SECRET

• OUTLOOK_ACCESS_TOKEN

• AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_STORAGE_ACCOUNT_NAME

Azure Table（定时发送队列）环境变量：

• AZURE_STORAGE_ACCOUNT_NAME（Storage Account 名称）

• AZURE_STORAGE_TABLE_NAME（可选，默认 EmailSendQueue）

• AZURE_TENANT_ID（Service Principal 租户 ID）

• AZURE_CLIENT_ID（Service Principal 客户端 ID）

• AZURE_CLIENT_SECRET（Service Principal 密钥）

Azure Table 所需 RBAC（Service Principal）：

• 建议最小权限：Storage Table Data Contributor

• 建议作用域：Storage Account 级别（支持表不存在时自动创建）

• 不建议仅分配 Contributor（管理面权限，通常不包含 Table 数据面读写）

触发批量发送（Service Principal）所需 Graph 应用权限：

• Mail.Send（Application）

• 建议同时配置 Mail.ReadWrite（Application）用于草稿与发送流程兼容

• 以上 Application 权限需管理员同意（Admin consent）

当前实现固定使用 /me 路由访问 Outlook 邮箱。

2.1.1 OAuth 2.0 Dynamic discovery

服务支持两种接入模式：

• 默认兼容模式：客户端直接发送 Authorization: Bearer <Graph token>

• DCR 模式：当 MCP_OAUTH_DYNAMIC_DISCOVERY_ENABLED=true 且 MCP_PUBLIC_BASE_URL / MCP_OAUTH_TENANT_ID / MCP_OAUTH_CLIENT_ID / MCP_OAUTH_CLIENT_SECRET 完整时，服务会自动暴露 OAuth 元数据与回调端点

启用 DCR 后会提供：

• /.well-known/oauth-authorization-server

• /.well-known/oauth-protected-resource

• /register / /authorize / /token / /revoke

• /oauth/callback

运行状态会写入 Azure Table：

• OAuthClientRegistry：客户端注册信息

• OAuthTokenRegistry：state / code / token / Graph token 映射

注意：

• MCP 访问令牌由本服务签发并校验

• 实际调用 Graph 时使用登录过程中获取的用户委托 token

• 若未启用 DCR，服务保持兼容模式，直接接收 Authorization: Bearer <Graph token>

Token 权限至少满足以下之一：

• Mail.Read / Mail.ReadWrite / Mail.Send

• Calendars.Read / Calendars.ReadWrite

• MailboxSettings.Read

默认地址：

• Host: 127.0.0.1

• Port: 80

• Path: /mcp

2.1.2 重置 VS Code 缓存的动态 Client ID（触发新 client_id）

当浏览器回调出现类似错误时：

{"error":"invalid_request","error_description":"Client ID '<old-client-id>' not found"}

通常是 VS Code 侧缓存了旧的 MCP 动态注册信息。可按以下方式重置。

方法一：命令面板清理（推荐）

1. 打开命令面板：Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS）。

2. 执行：Authentication: Remove Dynamic Authentication Provider。

3. 在列表中选择你的 MCP 服务（例如 mail-assist-mcp-local）。

4. 确认后，VS Code 会删除该服务对应的动态 client_id 和关联认证缓存。

5. 下次重新连接 MCP 服务时，会重新走 OAuth/DCR 流程并生成新的 client_id。

方法二：手动清理本地缓存（高级）

1. 完全退出 VS Code。

2. 清理当前用户的 VS Code 缓存目录中与 MCP/OAuth 相关的条目（重点检查 User/globalStorage 与 User/workspaceStorage）。

3. 重新打开 VS Code，再次连接该 MCP 服务，触发新的动态注册。

说明：

• 你当前仓库的 .vscode/mcp.json 仅配置服务器地址，不保存动态 client_id。

• 如果服务端也清理了 OAuthClientRegistry，而客户端未清理缓存，也会出现同样错误；此时优先执行方法一。

2.2 反向代理与 HTTPS

建议把 mail-mcp 仅暴露到内网 HTTP，并由 Nginx/Caddy 负责 443 TLS 终结。核心思路是：

• 后端监听 127.0.0.1:80

• 反向代理转发 /mcp 到后端

• 对外仅提供 HTTPS 地址，例如 https://mcp.example.com/mcp

2.3 定时发送

服务提供一个批量发送入口：

• GET /jobs/dispatch

它会扫描 Azure Table EmailSendQueue 中已到期的 pending / scheduled 任务，并用 Service Principal 调用 Graph 发送对应草稿。成功写入 sent，失败写入 failed 和 lasterror。

4. 集成说明

• 本服务通过 /mcp 暴露 MCP 工具

• /mcp 请求必须带 Authorization: Bearer <token>

• 对于 Copilot Studio，可使用 OAuth 2.0 -> Manual 方式接入

• 建议使用独立 Entra 应用注册进行隔离，便于审计、权限控制和密钥轮换

• 最小推荐 scope：offline_access openid profile Mail.Read Mail.ReadWrite Mail.Send Calendars.Read Calendars.ReadWrite MailboxSettings.Read

5. 约束与注意事项

• Graph 默认后端：MAIL_MCP_BACKEND=graph

• EWS 后端仅在 MAIL_MCP_BACKEND=ews 时启用，并且仅使用 bearer token，不兼容用户名/密码

• EWS 只从当前登录用户的 bearer token 中解析邮箱，不支持指定邮箱或共享邮箱

• EXCHANGE_SERVER_URL 必须指向真实 EWS 端点，不要只填域名

• OUTLOOK_ACCESS_TOKEN 仅用于调试兜底；生产环境应优先使用请求头中的 token