Outlook Personal MCP

outlook-personal-mcp

一个 MCP 服务，通过 Microsoft Graph API 让 Claude Code 和 Codex 全面控制个人 Outlook.com 邮箱和日历。使用 Python 编写，通过 MCP stdio 传输方式通信，并采用每用户设备代码 OAuth，因此你的凭据不会离开本机。采用 MIT 许可证。

---

功能

• 邮件 — 列出、搜索、读取、发送、回复、转发、移动、复制、标记、标记为已读/未读、删除（软删除或永久删除）
• 草稿 — 创建、更新、附加本地文件、发送
• 文件夹 — 列出、创建、重命名、删除
• 日历 — 列出日历，列出/搜索/获取/创建/更新/删除事件，回复邀请（接受/拒绝/暂定），检查空闲/忙碌状态
• 每用户 OAuth — 注册你自己的免费 Azure 应用；服务使用你的 Microsoft 账户进行身份验证，并在本地缓存令牌
• 本地 stdio — 作为 MCP 主机的子进程运行；你的邮箱数据绝不会经过第三方

---

先决条件

• Python 3.10 或更高版本
• uv（快速的 Python 包和工具运行器）——运行时必需：服务通过 uvx 启动，MCP 主机（包括 Claude Desktop）不会捆绑它。使用 curl -LsSf https://astral.sh/uv/install.sh | sh（macOS/Linux）或 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"（Windows）安装。
• 个人 Microsoft 账户（Outlook.com、Hotmail、Live 等）
• 免费 Azure 应用注册（见下文，大约需要三分钟）

---

Azure 应用注册

1. 前往 https://portal.azure.com → Microsoft Entra ID → 应用注册 → 新注册。

2. 名称任意（例如 outlook-personal-mcp）。在 支持的帐户类型 下选择 仅个人 Microsoft 帐户。无需重定向 URI。点击 注册。

3. 打开应用 → 身份验证 → 高级设置 → 允许公共客户端流 → 设置为 是 → 保存。（此设置是本服务使用设备代码登录流程所必需的。）

4. 前往 API 权限 → 添加权限 → Microsoft Graph → 委托的权限，然后添加：

   • Mail.ReadWrite
   • Mail.Send
   • Calendars.ReadWrite

   （默认已包含 User.Read；运行时会自动请求 offline_access，无需手动添加。）

5. 从 概述 页面复制 应用程序（客户端）ID。这是你的 OUTLOOK_MCP_CLIENT_ID。

或者：使用 Azure CLI 创建应用

如果你有 az CLI，只需运行一条命令即可完成整个注册：

az login --use-device-code --allow-no-subscriptions   # sign in with your personal account

az ad app create \
  --display-name "outlook-personal-mcp" \
  --sign-in-audience PersonalMicrosoftAccount \
  --is-fallback-public-client true \
  --required-resource-accesses '[{"resourceAppId":"00000003-0000-0000-c000-000000000000","resourceAccess":[{"id":"024d486e-b451-40bb-833d-3e66d98c5c73","type":"Scope"},{"id":"e383f46e-2787-4529-855e-0e479a3ffac0","type":"Scope"},{"id":"1ec239c2-d7c9-4623-a91a-a9775856bb36","type":"Scope"}]}]' \
  --query appId -o tsv

输出的 appId 就是你的 OUTLOOK_MCP_CLIENT_ID。（这些 GUID 对应 Microsoft Graph 委托范围 Mail.ReadWrite、Mail.Send 和 Calendars.ReadWrite。）**注意：**全新的应用注册需要几分钟才能同步到 Microsoft 的消费者登录终结点。如果首次登录因 AADSTS700016（“找不到应用程序……”）失败，请等待几分钟后重试。

---

安装和首次登录

运行一次性交互式登录。程序会显示一个简短 URL 和代码；在任意浏览器中打开该 URL，输入代码并批准权限即可。令牌会缓存在 ~/.config/outlook-personal-mcp/token_cache.bin（权限模式 600），之后每次运行时都会自动刷新——除非刷新令牌过期或被撤销，否则不会再次提示你登录。

OUTLOOK_MCP_CLIENT_ID=<your-app-client-id> uvx mcp-outlook-personal login

如果要从源代码运行最新的未发布版本，而不是 PyPI 版本，请将 mcp-outlook-personal 替换为 --from git+https://github.com/salahawad/outlook-personal-mcp mcp-outlook-personal。

---

配置 Claude Code

将服务添加到项目的 .mcp.json（或者添加到 ~/.claude/.mcp.json，以用于所有项目）：

{
  "mcpServers": {
    "outlook": {
      "command": "uvx",
      "args": ["mcp-outlook-personal"],
      "env": { "OUTLOOK_MCP_CLIENT_ID": "<your-app-client-id>" }
    }
  }
}

或者，使用 CLI：claude mcp add。

---

配置 Codex

将服务添加到 ~/.codex/config.toml：

[mcp_servers.outlook]
command = "uvx"
args = ["mcp-outlook-personal"]
env = { OUTLOOK_MCP_CLIENT_ID = "<your-app-client-id>" }

---

安装为 Claude Desktop 扩展（.mcpb）

此服务也打包为 Claude Desktop 扩展（.mcpb）。从代码库检出目录构建此软件包：

npx @anthropic-ai/mcpb pack . dist/mcp-outlook-personal.mcpb

然后在 Claude Desktop 中打开 设置 → 扩展，安装 dist/mcp-outlook-personal.mcpb 文件，并在出现提示时输入你的 Azure 应用客户端 ID（以及任何可选设置）。

**要求：**该扩展使用 uvx mcp-outlook-personal 启动服务，因此必须安装 uv 并将其添加到 PATH 中 — Claude Desktop 不会随附它（参见先决条件）。Codex 和其他 stdio 主机使用上方的配置，而不是 .mcpb。

---

配置（环境变量）

变量	必需	默认值	说明
OUTLOOK_MCP_CLIENT_ID	是	—	Azure 应用的应用程序（客户端）ID
OUTLOOK_MCP_AUTHORITY	否	https://login.microsoftonline.com/consumers	MSAL 授权 URL（仅在迁移到工作或学校租户时更改）
OUTLOOK_MCP_TOKEN_CACHE	否	~/.config/outlook-personal-mcp/token_cache.bin	MSAL 令牌缓存文件的路径
OUTLOOK_MCP_FILE_ROOT	否	~/.local/share/outlook-personal-mcp/files	add_attachment 只能读取此目录下的文件，download_attachment 只能将文件写入此目录
OUTLOOK_MCP_MAX_FILE_BYTES	否	3145728	本地附件读取和附件下载允许的最大字节数
OUTLOOK_MCP_ALLOW_PERMANENT_DELETE	否	false	设置为 true 以启用 permanent_delete 工具（不可撤销 — 见下文）
OUTLOOK_MCP_DEBUG	否	false	设置为 true，将每个 Graph 请求的方法、URL 和 HTTP 状态码记录到 stderr。绝不会记录令牌或邮件内容。

---

工具

账户

工具	说明
whoami	返回已登录用户的 Microsoft 账户资料

邮件

工具	说明
list_messages	列出邮件（最新的排在前面）；可按文件夹筛选或仅显示未读邮件
search_messages	在整个邮箱中进行全文搜索（Graph $search）
get_message	获取单封邮件；可选择包含完整正文
list_attachments	列出邮件的附件（ID、名称、大小、内容类型）
download_attachment	将附件下载到 OUTLOOK_MCP_FILE_ROOT 下的路径（如果文件已存在，则拒绝覆盖）
send_mail	发送邮件
reply	回复邮件（使用 reply_all 可回复所有人）
forward	将邮件转发给收件人，并可附带评论
move_message	将邮件移至其他文件夹
copy_message	将邮件复制到其他文件夹
mark_read	将邮件标记为已读或未读
flag_message	为邮件添加或取消标记
delete_message	删除邮件（将其移至“已删除邮件”；可撤销）
permanent_delete	永久删除邮件（不可撤销）。仅当 OUTLOOK_MCP_ALLOW_PERMANENT_DELETE=true 时可用

文件夹

工具	说明
list_folders	列出邮件文件夹及未读和邮件总数
create_folder	创建邮件文件夹；可选择将其嵌套在父文件夹下
rename_folder	重命名邮件文件夹
delete_folder	删除邮件文件夹（将其移至“已删除邮件”）

草稿

工具	说明
create_draft	创建邮件草稿（不会发送）
update_draft	更新草稿的主题和／或正文
add_attachment	将本地文件（OUTLOOK_MCP_FILE_ROOT 下的普通非符号链接文件）附加到草稿
send_draft	发送现有草稿

日历

工具	描述
list_calendars	列出用户的日历
list_events	列出事件；如果提供了 start/end（ISO 8601），则返回该时间段内的事件
search_events	按自由文本搜索事件
get_event	获取单个事件，包括正文、与会者和在线会议链接
create_event	创建日历事件，可选择添加与会者和在线会议
update_event	更新现有事件的字段（仅更改提供的字段）
delete_event	删除/取消日历事件
respond_event	回复会议邀请：accept、decline 或 tentative
find_availability	获取一组人员在指定时间段内的忙闲情况

---

永久删除

permanent_delete 工具会绕过“已删除邮件”文件夹，永久移除邮件。该工具默认处于禁用状态——如果未设置 OUTLOOK_MCP_ALLOW_PERMANENT_DELETE（或其值为 false），MCP 服务就不会注册该工具，因此它不会出现在工具列表中。

若要启用该工具，请在 .mcp.json / config.toml 的服务环境配置块中设置 OUTLOOK_MCP_ALLOW_PERMANENT_DELETE=true。只有在了解后果后才这样做：此操作无法撤销，个人账户也没有“可恢复项目”恢复路径。

---

安全

• 令牌缓存属于凭据。 ~/.config/outlook-personal-mcp/token_cache.bin 文件包含一个长期有效的刷新令牌。该文件的权限设为 600，但仍应像对待密码一样保护它——切勿提交或分享，并将其存储在加密卷上。
• 数据保留在本地。 服务通过标准输入输出（stdio）作为 Claude Code / Codex 的子进程运行。邮箱内容会直接在 MCP 主机与 Microsoft Graph API 之间传递；不涉及第三方中继。
• 撤销访问权限。 若要撤销访问权限，请删除令牌缓存文件，和/或访问 https://account.microsoft.com/permissions 移除 Azure 应用的授权。你也可以直接从门户中删除 Azure 应用注册。
• 文件路径。 download_attachment 只会在 OUTLOOK_MCP_FILE_ROOT 下写入文件，并拒绝覆盖现有文件。add_attachment 只会读取 OUTLOOK_MCP_FILE_ROOT 下的普通非符号链接文件。相对路径会在该根目录下解析；根目录之外的绝对路径（以及任何经过符号链接的路径）都会被拒绝。两个工具都会遵守 OUTLOOK_MCP_MAX_FILE_BYTES 的限制。确认任何涉及文件系统的工具调用前，请先检查这些路径。

---

开发

git clone https://github.com/salahawad/outlook-personal-mcp
cd outlook-personal-mcp
uv venv && uv pip install -e ".[dev]"
uv run pytest
uv run ruff check .

---

隐私政策

此服务完全在你的计算机上运行，数据只会在你的计算机与 Microsoft Graph API 之间传递——没有第三方中继、没有遥测，维护者也不会收到任何信息。OAuth 令牌会缓存在本地的 ~/.config/outlook-personal-mcp/token_cache.bin 文件中（权限为 600）。完整的隐私政策请参阅 PRIVACY.md。

---

许可证

MIT — 详见 LICENSE。