Microsoft Planner

mcp-planner

通过 Microsoft Graph API 使用 Microsoft Planner 的 MCP 服务。查找组和计划、列出存储桶和任务，以及创建、更新、分配、完成或删除任务——包括描述和清单，并自动处理 Planner 的 ETag 并发控制。

与 mcp-itglue 和 mcp-connectwise-psa 是同系列项目——采用相同的架构。

工具

工具	描述
planner_search_groups	按名称查找 Microsoft 365 组（Teams）→ 组 ID
planner_find_user	按名称/UPN 查找用户 → 用于分配的用户 ID
planner_list_plans	列出某个组拥有的计划
planner_get_plan	计划及其存储桶
planner_create_bucket	在计划中创建存储桶
planner_list_tasks	列出计划或存储桶中的任务（按受分配者、未完成/已完成筛选）
planner_list_user_tasks	列出分配给某个用户的所有任务，涵盖多个计划
planner_get_task	获取任务及其描述和清单
planner_create_task	创建任务（存储桶、截止日期、优先级、受分配者、描述）
planner_update_task	更新标题/存储桶/截止日期/优先级/进度/受分配者
planner_update_task_details	更新描述；添加清单项或勾选/取消勾选清单项
planner_delete_task	永久删除任务
graph_find_endpoint †	搜索精心整理的 /planner、/groups、/users Graph 接口目录
graph_get †	对 /planner、/groups、/users 下的任意 Graph v1.0 路径执行只读 GET

† 高级工具集（选择启用，默认关闭）——用于访问精心整理的工具未封装的 Graph 接口。设置 PLANNER_ADVANCED_TOOLSET=true 或使用 --advanced 启用。graph_get 仅允许 GET，拒绝 /beta，且只能访问上述三个路径前缀，因此共享应用注册的其他权限（例如邮件）仍无法使用。

设置

1. Entra ID 应用注册

1. Entra 管理中心 → 应用注册 → 新注册
2. API 权限 → 应用程序权限 → 添加 Tasks.ReadWrite.All、GroupMember.Read.All、User.Read.All → 授予管理员同意
3. 证书和密码 → 新客户端密码 — 记下其值

2. 运行

MS_TENANT_ID=<tenant> MS_CLIENT_ID=<client-id> MS_CLIENT_SECRET=<secret> npx -y mcp-planner

Claude Code：

claude mcp add planner --env MS_TENANT_ID=<tenant> --env MS_CLIENT_ID=<client-id> --env MS_CLIENT_SECRET=<secret> -- npx -y mcp-planner

HTTP 模式

npx -y mcp-planner --transport http --port 3000

每个会话都通过请求进行身份验证（BYOK），需要提供 x-ms-tenant-id 和 x-ms-client-id，以及 以下二者之一：x-ms-client-secret（仅应用）或 x-ms-refresh-token（委托模式——见下文）；如果未设置这些请求头，则回退到 MS_* 环境凭据。如果同时提供密码和刷新令牌，则以刷新令牌为准（请求头覆盖代理可以添加请求头，但无法移除请求头）。健康探测地址为 GET /health。

委托模式 — 以已登录用户的身份操作

仅应用会话以应用注册的身份操作；委托会话则以用户身份操作：适用该用户的 Planner 权限，且每次写入都会归属到该用户。

1. 使用单独的公共应用注册：身份验证 → 允许公共客户端流 → 是；API 权限 → 委托权限 Tasks.ReadWrite、Group.Read.All、User.ReadBasic.All（+ 在租户要求时授予管理员同意）。
2. 每位用户通过设备代码助手登录一次，并妥善保存输出的刷新令牌：

node scripts/device-login.mjs --tenant <tenant-id> --client <public-client-id>

3. 使用 MS_REFRESH_TOKEN 替代 MS_CLIENT_SECRET（stdio），或使用 x-ms-refresh-token 请求头（HTTP）。在 MCP 网关后方，将其注册为个人凭据（字段 x-ms-refresh-token）。

刷新令牌是机密信息——它能以你的身份操作——自上次使用起约 90 天内有效；过期后请重新运行助手。

Docker

docker build -t mcp-planner .
docker run -p 3000:3000 -e MS_TENANT_ID=... -e MS_CLIENT_ID=... -e MS_CLIENT_SECRET=... mcp-planner

访问模型

MCP 层不进行角色限制：Entra 应用注册获授的 Graph 权限就是访问控制。通过 BYOK 请求头让会话指向不同的应用注册，从而限定其可执行的操作。

备注

• Planner 要求每次更新或删除时都提供 If-Match ETag — 工具会获取当前资源并自动传递其 ETag。如果遇到 412（并发更改），只需重试。
• 优先级映射：urgent=1，important=3，medium=5，low=9（Graph 使用 0–10）。
• 进度：未开始（0），进行中（50），已完成（100）。

开发

npm install
npm run dev        # stdio
npm run dev:http   # http
npm test
npm run build
npm run bundle     # Claude Desktop .mcpb

许可证

MIT