MCP Outlook

一个面向 Windows 桌面版 Microsoft Outlook 的本地 Model Context Protocol (MCP) 服务器。 它通过 Outlook COM 接口让支持 MCP 的 AI 客户端读取、搜索和整理邮件， 并以“先创建草稿、再显式发送”的方式辅助撰写回复或新邮件。

项目支持 stdio 与 Streamable HTTP 两种传输模式，无需 Microsoft Graph 或云端邮件 API。邮件数据默认在本机处理，适合个人办公自动化、邮件检索、 草稿生成和 AI Agent 工作流。

功能

• 获取邮件列表，支持文件夹、分页和未读状态筛选

• 读取纯文本或 HTML 邮件正文及附件元数据

• 按主题、发件人、正文、日期、附件和重要性搜索邮件

• 标记已读/未读、移动和删除邮件

• 创建回复、回复全部、转发或全新邮件草稿

• 使用 Markdown 生成 Outlook/Word 兼容的 HTML 正文

• 搜索联系人、查看发件人信息和展开通讯组

• 递归列出或创建 Outlook 文件夹

• 记录敏感写操作的审计日志

• 提供健康检查、运行指标和可选的 HTTP API Key 鉴权

• 自动重试临时 COM 错误并周期性回收连接

Related MCP server: outlook-mcp

运行要求

• Windows 10 或 Windows 11

• Python 3.10+

• 已安装并配置 Microsoft Outlook 桌面版

• Outlook 配置文件中已有可访问的邮箱

快速开始

1. 克隆并安装

git clone https://github.com/<your-account>/mcp-outlook.git
Set-Location mcp-outlook

python -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

如果 PowerShell 禁止执行虚拟环境激活脚本，可以不激活环境，直接使用 .\venv\Scripts\python.exe 执行后续命令。

2. 创建配置

Copy-Item .env.example .env

默认配置只监听 127.0.0.1:8000。常用配置项如下：

.env、日志、审计记录和虚拟环境均已加入 .gitignore，不要将真实凭据或邮件 数据提交到仓库。

启动方式

stdio 模式

stdio 适合由本机 MCP 客户端直接启动，不需要开放网络端口。

{
  "mcpServers": {
    "outlook": {
      "command": "C:\\path\\to\\mcp-outlook\\venv\\Scripts\\python.exe",
      "args": ["-m", "src.mcp_outlook.server"],
      "cwd": "C:\\path\\to\\mcp-outlook",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "PYTHONPATH": "C:\\path\\to\\mcp-outlook"
      }
    }
  }
}

将示例中的 C:\path\to\mcp-outlook 替换为仓库的实际绝对路径，然后重启 MCP 客户端。

HTTP 模式

使用默认的本地监听配置启动：

$env:MCP_TRANSPORT = "http"
.\venv\Scripts\python.exe -m src.mcp_outlook.server

也可以运行项目脚本：

.\start-network.bat

start-network.bat 会监听 0.0.0.0:8000，用于局域网或隧道场景。启用网络访问 前，建议在 .env 中配置高强度的 MCP_OUTLOOK_API_KEY，并使用防火墙限制来源。

HTTP 端点：

配置 API Key 后，请求 /mcp 和 /metrics 时需要提供 X-API-Key 请求头；/health 保持可用于健康探测。

可用工具

完整参数、返回结构和调用示例请参阅 MCP 工具接口规范。

安全设计

• 默认仅监听本机回环地址

• HTTP 模式支持 API Key

• 创建和修改邮件时默认保存为草稿，发送需要单独调用 send_draft

• 删除、移动、发送和草稿修改等操作写入本地审计日志

• 查询字符串在进入 Outlook DASL/Jet 查询前进行转义

• 日志、审计数据和 .env 不纳入版本控制

MCP 客户端仍可能读取或修改真实邮箱。请仅向可信客户端开放服务，并在发送、 删除或批量移动邮件前确认操作参数。

开发与测试

.\venv\Scripts\python.exe -m unittest discover -s tests -v

项目结构：

src/mcp_outlook/   Outlook COM、MCP 工具、配置、日志与服务入口
tests/             标准库 unittest 测试
docs/              需求、架构、模块设计与 API 规范

更多设计资料见 docs/design/README.md。

已知限制

• 仅支持 Windows 桌面版 Outlook，不支持新版 Outlook WebView 客户端或 Outlook Web

• 邮件移动到其他文件夹后，Outlook EntryID 可能发生变化

• COM 操作依赖当前 Windows 用户会话和 Outlook 配置文件

• 在无人登录的 Windows 服务会话中运行 Outlook COM 可能不稳定

License

本仓库尚未包含开源许可证文件。公开发布前请根据实际使用计划补充许可证。