Outlook Desktop MCP

outlook桌面mcp

  

将正在运行的Outlook桌面转换为MCP服务器。 没有Microsoft Graph API，没有Entra应用程序注册，没有OAuth令牌-只有您的本地Outlook和您已经拥有的身份验证。

然后，任何MCP客户端（Claude Code、Claude Desktop等）都可以通过现有的Outlook会话发送电子邮件、管理日历、创建任务、处理附件等。

快速开始

1.安装 （需要Python 3.12+）：

pip install outlook-desktop-mcp

2.注册克劳德代码：

claude mcp add outlook-desktop -- outlook-desktop-mcp

3.打开Outlook并启动Claude Code会话。 就是这样——工具可以立即使用。

工作原理——平台路由

当服务器启动时，它会检查它在哪个操作系统上运行，并采取以下两条路径之一：

                        outlook-desktop-mcp starts
                                  |
                          sys.platform check
                         /                  \
                   "win32"                "darwin"
                      |                      |
              ┌───────┴────────┐    ┌────────┴────────┐
              │  server.py     │    │  server_mac.py   │
              │  COM Bridge    │    │  AppleScript     │
              │  (29 tools)    │    │  Bridge          │
              │                │    │  (22 tools)      │
              └───────┬────────┘    └────────┬─────────┘
                      |                      |
              OUTLOOK.EXE via         Microsoft Outlook
              COM / STA thread        via osascript
                      |                      |
              Exchange / M365         Exchange / M365

这两条路径都使用本地运行的Outlook应用程序及其现有的已验证会话。 没有云凭据，没有Graph API令牌-服务器继承Outlook登录的任何帐户。

为什么是两条路？

Windows Outlook（经典版）公开了一个丰富的COM自动化接口——Outlook对象模型(MSOUTL.OLB).20多年来，这一直是以编程方式控制Windows上Outlook的标准方式。它提供了对邮件规则、类别、MAPI属性和完整文件夹层次结构的深入访问。

Mac Outlook不支持COM。相反，它公开了一个AppleScript字典，可以通过 osascript 命令。AppleScript接口涵盖了核心操作——电子邮件、日历、任务——但不公开规则、类别或某些高级MAPI功能。这是微软选择在Outlook for Mac脚本字典中包含的内容的限制，而不是此项目的限制。

服务器被构造为具有相同工具名称和签名的两个并行实现，因此无论平台如何，MCP客户端都能看到相同的接口。在给定平台上不可用的工具根本不会注册。

需求

视窗

• Outlook桌面（经典版） --the OUTLOOK.EXE 这是微软365/Office附带的。新的“现代”观(olk.exe)确实如此 不 支持COM
• Python 3.12+ （x64或ARM64）
• Outlook必须正在运行 MCP服务器启动时

支持x64和ARM64 Windows。在ARM64上，所有依赖项(pywin32, mcp, pydantic-core, cryptography, cffi, rpds-py)已预先构建 win_arm64 轮子——看 ARM64安装说明 下面是一个额外的 pip 你需要的旗帜。

Outlook“程序化访问”安全提示

当MCP服务器首次接触Outlook的COM API时，Outlook可能会显示一个对话框： *“某个程序正试图访问Outlook中存储的电子邮件地址信息”* （对象模型保护/程序化访问提示）。这是Outlook对恶意自动化的保护。

您有三个选择：

1. 点击“允许访问10分钟” 每次你开始一个会话。适合休闲使用。

1. 将防病毒状态设置为“有效” 在 *文件>选项>信任中心>信任中心设置>编程访问*当这行读起来 Valid，“从不警告我可疑活动”单选按钮变为可选，提示消失。在大多数配备当前Defender的个人电脑上，这都是开箱即用的。

1. 应用注册表策略 在 docs/suppress-outlook-oom-prompts.reg.从一个 高架的 PowerShell或命令提示符（Win+X→ *终端（管理员）*)，运行：

   reg import "C:\path\to\outlook-desktop-mcp\docs\suppress-outlook-oom-prompts.reg"

然后完全退出Outlook（检查任务管理器中的杂散 OUTLOOK.EXE 进程）并重新打开它。这将写入 AdminSecurityMode=3 并批准所有 PromptOOM* 类别下 HKLM\Software\Policies\Microsoft\Office\16.0\Outlook\Security，无论AV状态如何，Outlook都会尊重这一点。在Intune/MDM管理的公司设备上， HKCU\Software\Policies\...\Outlook 已锁定，HKLM密钥可能会在下次策略同步时被覆盖——如果 reg import 如果失败或提示返回，请IT通过组策略推送等效设置。

Windows 11 ARM64注释： Defender未在Outlook中注册 IOfficeAntiVirus ARM64上的接口，因此信任中心显示 *“防病毒状态：无效”* 和那个 *“永远不要警告我可疑活动”* 收音机一直处于灰色状态 即使Outlook以管理员身份启动选项2在ARM64上不可用；这 reg import 选项3是唯一持久的抑制路径。

macOS

• 微软Mac版Outlook --版本16.x或更高版本
• Python 3.12+
• Outlook必须正在运行 MCP服务器启动时

所需的macOS权限

工具首次运行时，macOS将显示 两个权限提示 您必须批准：

1. 隐私和自动化 --系统对话框询问： *“python3.12想要控制Microsoft Outlook”*。单击 允许 让服务器向Outlook发送AppleScript命令。

1. 无障碍 --要读取Exchange/M365收件箱，服务器使用macOS UI脚本（系统事件）。这需要无障碍访问 python3.12:

- 打开 系统设置>隐私和安全>辅助功能 - 找到 Python 3.12 在列表中（它出现在第一个提示之后） - 快捷开关 上

如果未启用辅助功能，日历、任务和本地文件夹工具将正常工作，但列出Exchange收件箱邮件将返回空结果。

这两种权限都是一次性设置的，macOS会记住它们以备将来使用。

按平台列出的可用工具

电子邮件

日历

任务

附件

类别、规则、外出（仅限Windows）

这些工具依赖于Outlook for Mac不通过AppleScript公开的COM特定API（MAPI属性访问器、规则对象模型和类别集合）。

总计：Windows上29个工具，macOS上22个工具。

建筑细部

Windows:COM网桥(com_bridge.py)

根据COM的要求，所有Outlook COM操作都使用单线程单元（STA）模型在专用线程上运行。异步MCP事件循环通过队列将工具调用分派到此线程并等待结果，从而遵守COM线程规则并保持MCP协议无阻塞。

MCP tool call (async)
  → bridge.call(func, args)
    → queued to STA thread
      → func(outlook, namespace, args) executes on COM thread
    → result returned via threading.Event
  → JSON response back to MCP client

每个工具的内部功能接收实时 Outlook.Application 和 MAPI.Namespace COM对象，并直接与Outlook对象模型配合使用-- GetItemFromID, CreateItem, Items.Restrict 使用DASL过滤器等。

macOS：AppleScript桥(applescript_bridge.py)

每个工具调用都会构建一个AppleScript字符串，并通过以下方式将其作为子进程执行 osascript。没有持久连接——每个调用都是无状态的。

MCP tool call (async)
  → build AppleScript string
    → asyncio.create_subprocess_exec("osascript", "-e", script)
    → parse stdout text into structured data
  → JSON response back to MCP client

每个工具都构造了一个AppleScript，可以在一个工具中获取所有需要的数据 osascript 调用（没有每条消息的子流程循环）。结果以分隔文本的形式返回，服务器将其解析为与Windows服务器生成的JSON结构相同的JSON结构。

与Windows的主要区别：

• macOS上的条目ID为 数字的 （例如。 42)，而不是十六进制字符串。它们标识文件夹上下文中的项目。
• 文件夹引用使用AppleScript的 独立于语言环境的关键字 (inbox, sent items, drafts, deleted items)而不是本地化的文件夹名称。
• 搜索使用AppleScript whose 条款（例如。 messages whose subject contains "query")而不是DASL过滤器。
• 用户输入被转义，以便安全地嵌入AppleScript字符串中，以防止脚本注入。

从源代码安装

Windows（x64）

git clone https://github.com/Aanerud/outlook-desktop-mcp.git
cd outlook-desktop-mcp
python -m venv .venv
.venv\Scripts\activate
pip install pywin32 "mcp[cli]" -e .
python .venv\Scripts\pywin32_postinstall.py -install

使用启动器脚本从源代码注册：

claude mcp add outlook-desktop -- powershell.exe -Command "& 'C:\path\to\outlook-desktop-mcp\outlook-desktop-mcp.cmd' mcp"

Windows（ARM64）

这 [cli] 额外的 mcp 暂时性地拉进来 cryptography，pip的默认解析器可能会选择一个缺少 win_arm64 wheel——然后无法构建，因为它需要Rust工具链和OpenSSL。安装时不使用 cli 额外和强制车轮分辨率：

git clone https://github.com/Aanerud/outlook-desktop-mcp.git
cd outlook-desktop-mcp
& "C:\Program Files\Python312-arm64\python.exe" -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install --only-binary=:all: pywin32 mcp
python -m pip install --no-deps -e .
python .venv\Scripts\pywin32_postinstall.py -install

基地 mcp 包足以运行stdio服务器-- [cli] 只需要额外的 mcp 开发人员CLI工具(mcp dev, mcp inspector)，在运行时不使用。

以与x64相同的方式从源代码注册：

claude mcp add outlook-desktop -- powershell.exe -Command "& 'C:\path\to\outlook-desktop-mcp\outlook-desktop-mcp.cmd' mcp"

macOS

git clone https://github.com/Aanerud/outlook-desktop-mcp.git
cd outlook-desktop-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]" -e .

从来源注册：

claude mcp add outlook-desktop -- /path/to/outlook-desktop-mcp/.venv/bin/python -m outlook_desktop_mcp

使用示例

注册后，只需自然地与克劳德交谈：

• *“显示我最近的10封收件箱电子邮件”*
• *“阅读Taylor关于MLADS的电子邮件”*
• *“发送电子邮件至alice@example.com关于项目更新”*
• *“这周我的日程表上有什么？”*
• *“创建会议bob@example.com明天下午2点30分钟”*
• *“将该电子邮件中的附件保存到我的下载文件夹”*
• *“创建一个任务来审查周五到期的季度报告，非常重要”*
• *“将该电子邮件标记为已读并将其移动到存档”*

仅Windows示例：

• *“我有哪些类别？将此电子邮件设置为‘跟进’”*
• *“列出我的邮件规则”*
• *“我被设置为不在办公室吗？”*

为什么不使用Microsoft Graph？

项目结构

outlook-desktop-mcp/
  src/outlook_desktop_mcp/
    entrypoint.py            # Platform detection → routes to correct server
    server.py                # Windows MCP server (29 tools, COM automation)
    server_mac.py            # macOS MCP server (22 tools, AppleScript)
    com_bridge.py            # Async-to-COM threading bridge (Windows)
    applescript_bridge.py    # Async osascript execution (macOS)
    tools/
      _folder_constants.py   # Outlook enums and constants (Windows)
    utils/
      formatting.py          # Email/event/task data extraction (Windows)
      errors.py              # COM error formatting (Windows)
      applescript_helpers.py # AppleScript escaping, date formatting (macOS)
  tests/
    phase1_com_test.py       # Email COM validation
    phase3_mcp_test.py       # Email MCP test
    calendar_com_test.py     # Calendar COM validation
    calendar_mcp_test.py     # Calendar MCP test
    extras_com_test.py       # Tasks/attachments/categories/rules/OOF COM test
    extras_mcp_test.py       # Tasks/attachments/categories/rules/OOF MCP test
  outlook-desktop-mcp.cmd   # Windows launcher script
  pyproject.toml

贡献

看 贡献.md 对于分支战略和发展设置。

许可证

看 许可证 文件。