mcp-outlook

mcp-outlook

一个默认安全的 Model Context Protocol 服务，用于通过 Microsoft Graph 操作 Microsoft Outlook 邮件。它允许 Agent 读取和操作邮箱——列出文件夹和邮件、进行全文搜索、读取正文和附件元数据、列出联系人；在更高权限模式下，还可创建草稿、发送／回复／转发邮件、标记为已读、移动邮件和删除邮件。它还可管理 OneDrive 文件——浏览、搜索、下载、上传、创建文件夹、移动／重命名和删除文件；以及管理日历——列出日历和事件、检查空闲／忙碌状态，并在受限权限下创建、更新、回复、取消和删除事件。

**浏览器登录：**首次运行时，它会打开浏览器并跳转到 Microsoft 登录页面，随后缓存令牌并在后台静默刷新——服务永远不会获取你的密码。

这是 dockndevai MCP 服务套件的一部分——所有服务共用一套治理模式。

它为 Agent 提供的功能

服务以只读模式启动（参见默认安全）；只有提高模式后，才会注册功能更强的工具。

工具	用途	所需模式
whoami	确认正在使用哪个邮箱	只读
list_folders	列出邮件文件夹及未读／总数	只读
list_messages	列出最近的邮件（按文件夹筛选，仅未读）	只读
search_messages	在整个邮箱中进行全文搜索	只读
get_message	获取一封邮件的完整正文和收件人	只读
list_attachments	获取附件元数据（不返回字节数据）	只读
list_contacts	列出个人联系人	只读
create_draft	准备草稿，但不发送	读写
send_mail	撰写并发送新邮件	读写 + OUTLOOK_ALLOW_SEND
reply_mail / forward_mail	回复（全部）／转发邮件	读写 + OUTLOOK_ALLOW_SEND
mark_read	标记为已读／未读（可撤销）	读写
move_message	移动到其他文件夹（可撤销）	读写
delete_message	删除（移至“已删除邮件”）	管理员 + OUTLOOK_ALLOW_DELETE
list_drive_items / get_drive_item	浏览 OneDrive 文件和文件夹	只读
search_drive_files	搜索 OneDrive	只读
download_drive_file	读取 OneDrive 文件文本	只读
upload_drive_file	创建／覆盖 OneDrive 文件	读写
create_drive_folder / move_drive_item	创建文件夹／移动并重命名	读写
delete_drive_item	删除 OneDrive 项目（→ 回收站）	管理员 + OUTLOOK_ALLOW_DELETE
list_calendars / list_events / get_event	浏览日历和事件（时间范围会展开重复事件）	只读
get_free_busy	在安排日程前检查人员的空闲情况	只读
create_event / update_event	创建／更新会议（邀请与会者）	读写 + OUTLOOK_ALLOW_SEND
respond_to_event	接受／拒绝／暂定接受邀请	读写 + OUTLOOK_ALLOW_SEND
cancel_event / delete_event	取消会议／删除事件	管理员 + OUTLOOK_ALLOW_DELETE

**访问权限最终由你的 Microsoft 账户已授予的权限范围决定。**日历工具需要委派权限范围 Calendars.ReadWrite（包含在默认范围内）。如果你的令牌未获得此权限的同意， Graph 会返回 403——套件的模式／标志是在 Microsoft 级别控制之上的纵深防御。 使用 OUTLOOK_SCOPES 缩小权限范围（例如移除 Calendars.ReadWrite，或使用 Calendars.Read 以实现只读访问）。

安装

npx -y @dockndevai/mcp-outlook

你需要注册一个 Entra（Azure AD）应用。对于默认的浏览器登录，请注册一个公共客户端并添加重定向 URI http://localhost（平台：移动和桌面应用程序），然后将其 应用程序（客户端）ID 用作 OUTLOOK_CLIENT_ID。授予委派的 Mail.Read 权限（如果你想发送或整理邮件，还需授予 Mail.Send / Mail.ReadWrite）。交互式使用无需客户端密钥。

更倾向于自动化？请改用仅应用身份验证：设置 OUTLOOK_CLIENT_SECRET + OUTLOOK_TENANT_ID + OUTLOOK_USER（参见身份验证）。

配置

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@dockndevai/mcp-outlook"],
      "env": {
        "OUTLOOK_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "OUTLOOK_TENANT_ID": "common",
        "OUTLOOK_MODE": "read-only"
      }
    }
  }
}

首次使用时，服务会打开浏览器供你登录，并将令牌缓存到 ~/.mcp-outlook/token.json（0600）；之后的运行会静默刷新令牌。

Claude Code / Cursor / Codex / VS Code / Windsurf 配置示例请参阅 docs/CLIENTS.md，所有受支持的变量请参阅 .env.example。

身份验证

身份验证模式会自动选择（可通过 OUTLOOK_AUTH 覆盖）：

• interactive（默认）— 仅设置 OUTLOOK_CLIENT_ID。使用带 PKCE 的授权码流程和环回重定向：浏览器会打开，你只需批准一次，访问令牌和刷新令牌便会缓存在磁盘上。操作已登录用户的邮箱（/me）。服务不会处理你的密码。
• client-credentials（仅应用）— 已设置 OUTLOOK_CLIENT_SECRET。服务会自行获取应用令牌；需要设置 OUTLOOK_TENANT_ID 和 OUTLOOK_USER（要操作的邮箱，因为应用令牌没有已登录用户）。为应用授予 Mail 应用程序权限并取得管理员同意。
• token — 将预先获取的 Graph Bearer 令牌设置为 OUTLOOK_TOKEN。令牌有效期由你管理。

默认安全

访问模型由 src/security.ts 强制执行，在 Graph 令牌自身的范围和角色之上提供纵深防御：

• OUTLOOK_MODE — read-only（默认）→ read-write → admin。只有模式允许其功能时，工具才会注册。只读模式开放 7 个读取工具；草稿和移动操作需要 read-write；删除操作需要 admin。
• OUTLOOK_ALLOW_SEND — 邮件发送（发送 / 回复 / 转发）无法撤销，因此除 read-write 外，还需要启用此标志。在 read-write 模式下始终允许创建草稿；发送之前，邮件不会离开邮箱。
• OUTLOOK_ALLOW_DELETE — 删除操作除需要 admin 模式外，还需要启用此标志。
• OUTLOOK_FOLDER_ALLOWLIST / OUTLOOK_PROTECTED_FOLDERS — 限定可写入或可移动到的文件夹；标记可读取但绝不可修改的文件夹（例如 sentitems、archive）。
• 交互式确认 — 当客户端支持 MCP 询问功能时，发送邮件和删除邮件会暂停并请求用户批准，然后才会执行；不支持询问功能的客户端则会通过 OUTLOOK_ALLOW_SEND / OUTLOOK_ALLOW_DELETE 进行限制。
• OUTLOOK_DRY_RUN — 验证并记录写入操作，但不执行。
• OUTLOOK_AUDIT_LOG — 每个受保护的操作都会在 stderr 输出一行 JSON 审计日志（默认开启）。
• 绝不返回附件字节数据 — list_attachments 只返回元数据。

请参阅 SECURITY.md。

开发

npm install
npm run build
# introspect the tool list without signing in (uses a fake token, no network):
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | OUTLOOK_TOKEN=x node dist/index.js
npm test

许可证

MIT