Skip to main content
Glama
MCP Outlook

MCP Outlook

by zx2015

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 配置文件中已有可访问的邮箱

IMPORTANT

本项目使用 Windows COM,因此不能直接运行在 Linux、macOS、GitHub Codespaces 或普通 Linux 容器中。运行服务的 Windows 用户必须能够正常启动 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。常用配置项如下:

环境变量

默认值

说明

MCP_OUTLOOK_HOST

127.0.0.1

HTTP 监听地址

MCP_OUTLOOK_PORT

8000

HTTP 监听端口

MCP_OUTLOOK_LOG_LEVEL

INFO

日志级别

MCP_OUTLOOK_LOG_FILE

logs/mcp-outlook.log

运行日志路径

MCP_OUTLOOK_DEFAULT_EMAIL_LIMIT

50

默认邮件返回数量

MCP_OUTLOOK_MAX_EMAIL_LIMIT

200

单次查询最大数量

MCP_OUTLOOK_COM_RECYCLE_INTERVAL

100

COM 连接回收间隔,0 表示不自动回收

MCP_OUTLOOK_API_KEY

空

HTTP 模式的可选 API Key

.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 端点:

地址

用途

http://127.0.0.1:8000/mcp

MCP Streamable HTTP

http://127.0.0.1:8000/health

Outlook 连接与服务健康状态

http://127.0.0.1:8000/metrics

工具调用和进程指标

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

可用工具

类别

工具

阅读与搜索

get_emails、read_email、search_emails、search_by_subject、search_by_sender、search_by_content

邮件操作

mark_as_read、move_email、delete_email

草稿与发送

create_reply_draft、create_forward_draft、create_new_draft、update_draft、send_draft

联系人与文件夹

get_sender_details、search_contacts、expand_distribution_list、list_folders、create_folder

运维与审计

get_recent_actions、restart_outlook

完整参数、返回结构和调用示例请参阅 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

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      A Model Context Protocol server that enables AI assistants to interact with Microsoft Outlook for calendar management, email operations, and search functionality.
      15
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides LLMs with access to Microsoft Outlook email functionality, allowing them to read, search, compose, and manage emails through a standardized MCP interface on Windows.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that gives AI assistants full access to Microsoft Outlook emails, calendar, and contacts via the Microsoft Graph API.
      2
      ISC