useful-outlook-mcp

一个面向 Microsoft Outlook 的远程 MCP 服务器，具备规范的 OAuth2 实现和为智能体优化的工具。

功能特性

• 符合规范：RFC 9728/8414 OAuth 元数据、RFC 7591 动态客户端注册

• 无状态 OAuth：令牌由客户端管理，而非服务器——这正是 OAuth 的本意

• 为智能体优化的工具：在工具描述中进行了大量提示工程

• 动态作用域：OAuth 作用域会根据启用的工具自动调整

• 生产就绪：Docker、速率限制、只读模式、工具过滤

Related MCP server: M365 MCP Server

快速开始

npm install
npm run build
npm start  # Server at http://localhost:3000

所需环境：

MS365_MCP_CLIENT_ID=your-azure-ad-client-id
MS365_MCP_CLIENT_SECRET=your-azure-ad-client-secret
MS365_MCP_TENANT_ID=your-tenant-id  # or 'common'

Azure AD 设置

1. Azure Portal → Microsoft Entra ID → 应用注册 → 新建

2. 添加委托权限：User.Read、Mail.Read、Mail.ReadWrite、Mail.Send、Calendars.Read、Calendars.ReadWrite、Calendars.Read.Shared、Place.Read.All、People.Read、offline_access

3. 添加重定向 URI：http://localhost:6274/oauth/callback（用于 MCP Inspector）

4. 证书和机密 → 新建客户端机密 → 复制该值

5. 将客户端 ID、客户端机密和租户 ID 复制到你的 .env 中

工具

邮件

list-mail-folders · list-mail-messages · search-mail · get-mail-message · send-mail · create-draft-mail · reply-mail · reply-all-mail · create-reply-draft · create-reply-all-draft · delete-mail-message · move-mail-message

日历

list-calendars · list-calendar-events · search-calendar-events · find-meeting-times · get-calendar-event · get-calendar-view · create-calendar-event · update-calendar-event · delete-calendar-event

联系人

lookup-contact-email

会议室搜索

对于线下会议，find-meeting-times 会自动：

• 获取你组织中所有可用的会议室

• 将它们与与会者一起纳入可用性检查

• 按位置（城市/大楼）对空闲会议室分组

• 仅返回带有邮箱地址的可预订空闲会议室

设置 isOnlineMeeting: false 即可启用会议室搜索。对于在线会议（默认值：true），会自动生成 Teams 会议链接。

所需作用域：Place.Read.All（添加到 Azure AD 应用权限中）

配置

Docker

从 GitHub Container Registry 拉取：

docker run -p 3000:3000 \
  -e MS365_MCP_CLIENT_ID=xxx \
  -e MS365_MCP_CLIENT_SECRET=xxx \
  -e MS365_MCP_TENANT_ID=xxx \
  ghcr.io/Leonine-Studios/useful-outlook-mcp:latest

或在本地构建：

docker build -t useful-outlook-mcp .
docker run -p 3000:3000 \
  -e MS365_MCP_CLIENT_ID=xxx \
  -e MS365_MCP_CLIENT_SECRET=xxx \
  -e MS365_MCP_TENANT_ID=xxx \
  useful-outlook-mcp

端点

测试

npm run dev
npx @modelcontextprotocol/inspector  # Connect to http://localhost:3000/mcp

设计说明

现有服务器的问题

1. 遗留架构：以 stdio 构建，HTTP 是后来硬接上去的。本服务器是 HTTP 原生实现。

2. OAuth 实现有误：大多数服务器将令牌存储在服务端。本服务器是无状态的——令牌通过 Authorization 头随每个请求传递，从不存储。

3. 工具未经思考：典型服务器只是将 API 端点 1:1 映射，没有任何指引。智能体在实际使用中会失败，因为它们不了解 API 的特殊行为和多步工作流。

不同之处

每个工具都包含：

• 何时使用它，而非替代方案

• 已知的 Graph API 特殊行为（有很多）

• 多步任务的工作流指引

• 会导致失败的参数组合

例如：find-meeting-times 会说明邮箱地址是必需的（仅用姓名无效）、如何使用 search-mail 根据姓名查找邮箱、OrganizerUnavailable 的含义，以及 isOrganizerOptional=true 需要用户确认。

已知的 Graph API 特殊行为

• 邮件发件人筛选：对 from/emailAddress/address 使用 eq 不可靠——应使用 startswith()

• 邮件收件人筛选：无法用 $filter 按收件人/抄送/密送筛选——必须使用 $search

• 日历组织者筛选：对组织者邮箱使用 $filter 会返回 500——已在客户端过滤

• 并发：并行调用可能返回 MailboxConcurrency 错误

• 搜索 + 排序：$search 不能与 $orderby 结合使用

许可证

MIT