outlook-mcp-server

一个本地 MCP 服务器，通过 Microsoft Graph API 并采用 OAuth 2.0 授权码流程（带 PKCE）对接 Microsoft 身份平台，让 Claude（桌面版或 Code）能够读写个人 Hotmail / Outlook.com 邮箱。

它提供六个工具：list_messages、get_message、search_messages、send_message、create_draft 和 list_folders。

一切都在本地通过 stdio 运行——没有托管服务，你的邮件只会经过你的机器和 Microsoft 自己的 Graph API。

工作原理

• 认证：MSAL Node 针对 https://login.microsoftonline.com/consumers（仅限个人账户——参见租户选择）运行授权码 + PKCE 流程，使用一个短命的本地 HTTP 服务器作为重定向目标。令牌（包括 offline_access 刷新令牌）会被缓存，并在后续运行时静默刷新。

• 存储：令牌缓存由 MSAL 序列化，使用本地生成的密钥通过 AES-256-GCM 加密，并写入 ~/.outlook-mcp-server/token-cache.enc（权限 0600）。密钥本身存放在 ~/.outlook-mcp-server/cache.key（同样为 0600）。参见安全说明了解此方案所覆盖（及未覆盖）的威胁模型。

• Graph 调用：一个基于 fetch 的轻量客户端使用当前访问令牌调用 https://graph.microsoft.com/v1.0/...。

• MCP 服务器：基于 @modelcontextprotocol/sdk 构建，通过 stdio 通信，因此可以直接被 Claude Desktop / Claude Code 作为子进程启动。

Related MCP server: Outlook MCP Python

前提条件

• Node.js 18+

• 一个 Microsoft 账户（Hotmail、Outlook.com 或 Live）——即你希望 Claude 访问的邮箱。

• 一个免费的 Azure 账户用于注册应用（任何 Microsoft 账户都可以——不需要付费的 Azure 订阅）。

1. 安装

git clone <this repo>
cd outlook-mcp-server
npm install

2. 在 Azure 门户中注册应用

此注册用于签发客户端 ID，服务器将使用该 ID 代表你与 Microsoft Graph 通信。npm run setup（见下文）会以交互方式引导你完成这些步骤，但具体步骤如下：

1. 前往 portal.azure.com 并使用任意 Microsoft 账户登录。

2. 搜索 应用注册 → + 新注册。

3. 填写表单：

   • 名称：任意，例如 outlook-mcp-server。

   • 受支持的账户类型：“仅个人 Microsoft 账户”。这会将应用限制为 Hotmail/Outlook.com/Live 账户，而不是工作或学校（Azure AD）租户。

   • 重定向 URI：平台 “公共客户端/本机（移动和桌面）”，值为 http://localhost:8765/callback（或使用其他端口——只需在设置脚本询问时保持一致）。

4. 点击 注册，然后从“概述”页面复制 应用程序（客户端）ID。

5. 前往 API 权限 → + 添加权限 → Microsoft Graph → 委托的权限，并添加：

   • Mail.Read

   • Mail.ReadWrite

   • Mail.Send

   • offline_access（通常默认已存在）

   个人 Microsoft 账户的此类委托权限无需管理员同意——你将在下面第 3 步的登录过程中自行同意。

6. （可选，高级） 如果你希望使用带客户端机密的机密客户端，而不是公共客户端的 PKCE 流程，请添加 Web 平台重定向 URI，并在 证书和机密 下创建机密。大多数人应跳过此步骤。

3. 运行设置（认证 + 配置）

npm run setup

这将：

1. 打印上述操作指南。

2. 提示输入客户端 ID（以及可选的机密 / 租户 / 重定向 URI），并将其保存到 ~/.outlook-mcp-server/config.json。

3. 打开浏览器进行登录和同意。

4. 通过调用 GET /me 验证令牌是否有效，并打印你的姓名/电子邮件。

5. 打印要添加到 Claude 配置中的 JSON 片段（见下文）。

如果之后需要重新认证（令牌被撤销、切换账户等），而无需重新输入应用注册详细信息：

npm run login

4. 构建并注册到 Claude

npm run build

Claude Desktop — 添加到 claude_desktop_config.json（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["/absolute/path/to/outlook-mcp-server/dist/src/index.js"]
    }
  }
}

Claude Code：

claude mcp add outlook -- node /absolute/path/to/outlook-mcp-server/dist/src/index.js

重启 Claude Desktop / Claude Code。以下工具现在应该可用。

工具

所有工具均返回 JSON（作为 MCP 文本内容），并将 Graph API 错误作为工具错误呈现，而不是导致服务器崩溃。

租户选择

默认使用 consumers 租户（https://login.microsoftonline.com/consumers），该租户仅接受个人 Microsoft 账户（Hotmail/Outlook.com/Live）——工作或学校账户将在登录时被拒绝。如果你需要同时支持个人账户和 Azure AD 账户，请在 npm run setup 期间将租户设置为 common（或通过 OUTLOOK_MCP_TENANT=common）。本项目针对个人账户（consumers）场景设计和测试。

配置参考

所有内容都可以通过 npm run setup（写入 ~/.outlook-mcp-server/config.json）或环境变量设置，环境变量优先——参见 .env.example：

安全说明

• 令牌缓存使用本地生成的 AES-256-GCM 密钥（~/.outlook-mcp-server/cache.key，权限 0600）进行静态加密。这可以防止意外泄露——意外提交、备份、共享机器上的其他非特权用户——但无法防止已经对你的用户账户文件具有读取权限的攻击者，因为密钥与加密缓存存放在一起。如需更强的保护，请将 src/auth/tokenCache.ts 中的 ICachePlugin 替换为基于操作系统钥匙串的实现（例如通过 keytar）——插件接口特意隔离在该文件中。

• 切勿提交 ~/.outlook-mcp-server/（默认位于仓库之外）或包含 OUTLOOK_MCP_CLIENT_SECRET 的 .env 文件。

• send_message 会立即发送，服务器内部没有确认步骤——Claude 应在调用它发送任何敏感内容之前与你确认意图。当你希望有审查步骤时，请优先使用 create_draft。

• 请求的范围仅限于 Mail.Read、Mail.ReadWrite、Mail.Send 和 offline_access——不涉及日历、联系人，也没有更广泛的 Mail.* 应用级访问。

故障排除

• AADSTS50020 / “用户账户 ... 在租户中不存在” — 你访问的租户不接受个人账户，或者你使用工作/学校账户登录了 consumers。请确认应用注册的“受支持的账户类型”为“仅个人 Microsoft 账户”，并且 OUTLOOK_MCP_TENANT 为 consumers（如果你有意同时支持两者，则为 common）。

• AADSTS50011 / 重定向 URI 不匹配 — ~/.outlook-mcp-server/config.json 中的 redirectUri 必须与 Azure 应用注册中配置的重定向 URI 完全匹配，包括端口。

• 工具报错“未登录” — 运行 npm run login。

• 设置/登录期间端口已被占用 — 另一个进程正在使用重定向 URI 的端口；停止该进程，或使用其他端口重新配置应用注册并运行 npm run setup。

开发

npm run dev     # run the MCP server directly from TypeScript (stdio)
npm run build   # compile to dist/
npm run clean   # remove dist/

项目结构

src/
  index.ts            MCP server entrypoint (stdio transport)
  config.ts            Config loading (env + config file)
  auth/
    crypto.ts           AES-256-GCM file encryption helpers
    tokenCache.ts        MSAL ICachePlugin backed by crypto.ts
    msalClient.ts        MSAL app factory + silent token acquisition
    loginFlow.ts          Interactive loopback OAuth flow
  graph/
    client.ts            Generic Microsoft Graph fetch wrapper
    mail.ts               Mail-specific Graph calls
    types.ts              Graph response types
  tools/                 One file per MCP tool, registered in index.ts
scripts/
  setup.ts              Interactive one-time (and re-runnable) setup