Mcp Microsoft Todo

mcp-microsoft-todo

🇫🇷 法语版本：README.fr.md

可通过 Claude Code、Claude Desktop 或任何兼容 MCP 的客户端操作 Microsoft To Do 的 MCP 服务。

适用于任何 Microsoft 帐户：个人帐户（outlook.com、hotmail.com、live.com）、个人或企业 Office 365、Microsoft 365。用户无需进行任何 Azure 设置，只需通过设备代码流登录即可。

---

🏗 由 MAG&Cie 构建并维护

此 MCP 服务是开源的，可免费使用。它也是我们在 MAG&Cie 提供的 MCP 创建服务的展示项目——我们为希望将 AI 接入内部工具（CRM、ERP、自定义 API、内部数据库）的企业构建定制 MCP 连接器。

如果你也希望为自己的工具配备此类连接器，请访问 www.mag-cie.com/creation-mcp 联系我们。

---

🚀 终端用户安装

前提条件（所有客户端）

• Node.js 20+（nodejs.org）
• 一个 Microsoft 帐户（免费或付费）

无需 Azure 帐户，无需创建应用注册，也无需编译。

---

🟦 Claude Code（CLI）

安装（一条命令）：

claude mcp add --transport stdio microsoft-todo -- npx -y @mag-cie/mcp-microsoft-todo

如果你使用的是个人 Microsoft 帐户（outlook.com、hotmail.com、live.com、msn.com、个人 Office 365），请添加 MS_TENANT=consumers：

claude mcp add --transport stdio microsoft-todo --env MS_TENANT=consumers -- npx -y @mag-cie/mcp-microsoft-todo

验证配置是否成功：

claude mcp list

首次使用——建议：先在终端中完成预先身份验证，以避免出现“首次调用 MCP 时卡住”的问题（设备代码会输出到 MCP 的 stderr，但 Claude Code 不会显示出来）：

# macOS / Linux
MS_TENANT=consumers npx -y @mag-cie/mcp-microsoft-todo@latest --auth

# Windows PowerShell
$env:MS_TENANT="consumers"; npx -y @mag-cie/mcp-microsoft-todo@latest --auth

你会看到：

To sign in, use a web browser to open the page https://www.microsoft.com/link and enter the code XXXXXXXXX

访问该 URL，输入代码并登录。令牌会缓存在 ~/.mcp-microsoft-todo/token-cache.json 中，并自动刷新——以后无需再次操作。现在打开 Claude Code，任何调用工具的提示词都能立即生效。

如果你愿意碰碰运气，可以跳过预先身份验证步骤——MCP 也会在首次调用时触发设备代码流。代码会写入 Claude Code 的 MCP 日志文件（Windows 上请查看 %USERPROFILE%\.claude\logs\，其他系统上请查看 ~/.claude/logs/）。

更新到最新版本：

claude mcp remove microsoft-todo
claude mcp add --transport stdio microsoft-todo -- npx -y @mag-cie/mcp-microsoft-todo@latest

npx 的 -y 标志会自动接受下载。若不使用 @latest，npx 可能会提供过时的缓存版本。

卸载：

claude mcp remove microsoft-todo
# Purge the token cache:
rm -rf ~/.mcp-microsoft-todo

---

🟪 Claude Desktop（应用）

1. 找到配置文件：

操作系统	路径
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

在 Windows 上，你可以直接打开该文件：

notepad $env:APPDATA\Claude\claude_desktop_config.json

如果文件不存在，请先创建一个空 JSON 对象 {}，然后进行编辑。

2. 添加配置：

{
  "mcpServers": {
    "microsoft-todo": {
      "command": "npx",
      "args": ["-y", "@mag-cie/mcp-microsoft-todo"]
    }
  }
}

如果使用个人 Microsoft 账户，请添加 env：

{
  "mcpServers": {
    "microsoft-todo": {
      "command": "npx",
      "args": ["-y", "@mag-cie/mcp-microsoft-todo"],
      "env": { "MS_TENANT": "consumers" }
    }
  }
}

若要本地化紧凑格式的字符串（可选，参见本地化）：

{
  "env": { "MS_TENANT": "consumers", "MCP_LOCALE": "fr" }
}

3. 完全重启 Claude Desktop（不只是关闭窗口）：

• Windows：右键单击系统托盘图标 → 退出，然后重新启动
• macOS：按 ⌘+Q，然后重新启动

4. 验证是否已连接：

在 Claude Desktop 中，查看输入区域右下角的 🔌 插头或 🔧 工具图标 — 你应该能看到 microsoft-todo。

5. 首次认证 — 建议先在终端中完成认证：

# macOS / Linux
MS_TENANT=consumers npx -y @mag-cie/mcp-microsoft-todo@latest --auth

# Windows PowerShell
$env:MS_TENANT="consumers"; npx -y @mag-cie/mcp-microsoft-todo@latest --auth

设备代码会立即显示在终端中。访问该 URL，输入代码并登录。令牌已缓存。现在 Claude Desktop 会重用此缓存 — 无需再从日志中查找。

如果未使用 --auth，设备代码会写入 Claude Desktop MCP 日志文件：

• Windows：%APPDATA%\Claude\logs\mcp-server-microsoft-todo.log
• macOS：~/Library/Logs/Claude/mcp-server-microsoft-todo.log

**更新：**编辑 args 中的版本（@mag-cie/mcp-microsoft-todo@latest），然后重启 Claude Desktop。或者让 npx 自行处理（npx 缓存约 24 小时）。

---

🟧 Cursor / Continue / 其他 stdio MCP 客户端

任何支持 stdio 传输的 MCP 客户端都可以使用相同方式。通用格式：

command: npx
args: -y @mag-cie/mcp-microsoft-todo
env: MS_TENANT=consumers (if personal account)

根据客户端的配置格式进行调整（通常是类似 Claude Desktop 的 JSON 或 TOML）。

---

💡 示例提示词

安装后，只需用自然语言向 Claude 提问。以下示例提示词可用于调用主要工具：

提示词	工具
“显示我的所有 To Do 列表”	list_task_lists
“我今天要做什么？”	summarize_today
“显示我的逾期任务”	list_overdue_tasks
“列出标记为‘工作’的任务”	list_tasks_by_category
“查找包含‘发票’的任务”	search_tasks
“添加一个每日重复的‘锻炼’任务”	create_task（含重复设置）
“将这 5 个任务标记为已完成”	batch_complete_tasks
“将‘买面包’从‘个人’移到‘购物’”	move_task
“为蛋糕任务添加一个‘食谱’子任务”	create_checklist_item
“将我所有的 Magaria 任务标记为‘紧急’”	bulk_update_categories
“将我的工作任务导出为 iCalendar”	export_tasks_ics
“为此任务添加 project_id 元数据”	set_extension

---

🆘 认证故障排查

症状	解决方案
登录后出现“This page isn't right”页面	添加 MS_TENANT=consumers（仅限个人账户）
浏览器打开了错误的 Microsoft 账户	使用 InPrivate/无痕窗口登录
出现 invalid_scope 或 Tasks.ReadWrite.Shared 错误	清除令牌缓存并重新认证：rm -rf ~/.mcp-microsoft-todo
找不到 Node.js 或 npx	从 nodejs.org 安装 Node 20+。在 Windows 上，确认它位于 PATH 中（安装后重新启动终端）
令牌已过期，刷新失败	清除缓存并重新认证
设备代码始终未显示	确认服务已启动 — Claude Code：claude mcp list；Claude Desktop：查看工具图标。如果未显示，请检查配置中的 npx PATH
MS_CLIENT_ID not configured	你正在使用开发分支 — 导出 MS_CLIENT_ID 或使用官方 npm 版本

---

🛠 可用工具（28）

安全性列说明：read = 只读，write = 修改状态（创建操作不可幂等），update = 幂等修改（可安全重试），delete = 破坏性操作（会导致数据丢失）。详情请参阅下文的安全性注解。

列表和任务

工具	安全级别	描述
list_task_lists	read	所有待办事项列表
list_tasks	read	某个列表中的任务（OData 筛选、$orderby、paginate）
get_task	read	按 ID 获取任务详情
create_task	write	创建任务（标题、正文、重要性、截止日期、类别、重复规则、提醒）
update_task	update	更新标题、状态、截止日期、重复规则、提醒……
complete_task	update	标记为已完成
delete_task	delete	永久删除
move_task	delete	将任务从一个列表移动到另一个列表（源任务会被删除）
search_tasks	read	按标题跨列表搜索
summarize_today	read	今日到期和逾期任务摘要
list_all_tasks	read	一次往返获取所有列表中的每个任务（使用 Graph $batch）

批量操作（节省 API 调用）

工具	安全级别	描述
batch_create_tasks	write	在一次 Graph $batch HTTP 调用中创建最多 100 个任务
batch_complete_tasks	update	在一次调用中将最多 100 个任务标记为已完成
batch_delete_tasks	delete	在一次调用中删除最多 100 个任务

子任务（清单项）

工具	安全级别	描述
list_checklist_items	read	任务的子项
create_checklist_item	write	添加子项
update_checklist_item	update	重命名 / 勾选 / 取消勾选
delete_checklist_item	delete	删除子项

关联资源（附加到任务的外部 URL）

工具	安全级别	描述
list_linked_resources	read	列出任务的关联资源
create_linked_resource	write	附加 URL 或外部引用
delete_linked_resource	delete	删除关联资源

开放扩展（自定义 JSON 元数据）

工具	安全级别	描述
list_extensions	read	列出任务的开放扩展
set_extension	update	插入或更新扩展（project_id、external_ref 等）
delete_extension	delete	删除扩展

跨列表辅助工具

工具	安全级别	描述
list_overdue_tasks	read	汇总所有列表中的逾期任务
list_tasks_by_category	read	跨列表获取指定类别的所有任务
bulk_update_categories	update	分两个批次阶段为多个任务添加或移除类别

导出

工具	安全级别	描述
export_tasks_ics	read	导出 iCalendar（VTODO + RRULE + VALARM），以便导入 Google Cal / Apple Cal / Outlook / Thunderbird

输出格式

默认情况下，工具会返回紧凑文本格式（每项一行），以节省大模型令牌。图例：

• [!] 高重要性，[?] 低重要性（普通时不显示）
• [v] 已完成，[>] 进行中，[w] 等待中，[d] 已延期（尚未开始时不显示）
• 仅在有值时显示 due:、rem:、rec:、cat:、body: 字段

如需获取完整的 Graph JSON，请向任何读取工具传入 verbose: true。

---

🔐 安全注解

此服务公开的每个工具都带有 MCP 工具注解，该注解由 Model Context Protocol 规范（2025-06-18）定义：

注解	含义
readOnlyHint	该工具只获取数据；运行时不会对 Microsoft Graph 产生副作用
destructiveHint	该工具会删除数据或以其他方式造成无法撤销的数据丢失
idempotentHint	使用相同参数重复运行该工具会得到相同的最终状态（可安全重试）
openWorldHint	该工具会与外部系统（Microsoft Graph）通信——此处始终为 true
title	面向用户的可读显示名称，供 MCP 客户端使用

这些提示仅供参考——服务本身不会强制执行任何操作——但 MCP 客户端（Claude Code、Claude Desktop、Cursor 等）可以利用它们：

• 自动批准 readOnlyHint: true 调用，无需提示用户（让以读取为主的工作流更快）
• 在 destructiveHint: true 调用前显示确认对话框（例如 delete_task、batch_delete_tasks、move_task）
• 仅在 idempotentHint: true 时针对暂时性故障进行重试
• 显示友好的 title，而非蛇形命名的 name

完整映射见 src/index.ts（ANNOTATIONS 常量）。按安全类别汇总如下（另请参阅上方各工具的安全性列）：

• 读取（15 个工具）：所有 list_*、get_*、search_*、summarize_*、export_*——readOnlyHint: true
• 写入（4 个工具）：create_*、batch_create_tasks——destructiveHint: false, idempotentHint: false
• 更新（5 个工具）：update_*、complete_*、set_extension、bulk_update_categories、batch_complete_tasks——destructiveHint: false, idempotentHint: true
• 删除（5 个工具）：delete_*、batch_delete_tasks、move_task——destructiveHint: true, idempotentHint: true

move_task 被归类为「删除」，因为它会删除源任务（并在目标列表中创建一个 ID 不同的新任务）。

---

🌍 本地化

MCP 开箱即支持任何语言——Claude 会读取服务返回的数据，并使用用户提示时所用的语言作答。试试 "List my tasks"、"Liste mes tâches"、"Zeig meine Aufgaben"、"我的任务"——都可以正常使用。

你也可以选择本地化服务返回的紧凑格式短标签（No tasks.、Due today:、Overdue:、Task X deleted. 等）——这只是细微的改进（可节省少量令牌，让大模型上下文稍微更整洁）。在环境中设置 MCP_LOCALE：

语言	代码
English（默认）	en
Français	fr
Español	es
Deutsch	de

解析顺序：MCP_LOCALE → LC_ALL → LANG → 回退到 en。仅检查前 2 个字符（因此 fr_FR.UTF-8 也可正常使用）。不支持的区域设置 → 回退到 en。

{
  "mcpServers": {
    "microsoft-todo": {
      "command": "npx",
      "args": ["-y", "@mag-cie/mcp-microsoft-todo"],
      "env": { "MCP_LOCALE": "fr" }
    }
  }
}

---

🔒 安全与隐私

• Microsoft 令牌仅存储在你的本地计算机上，路径为 ~/.mcp-microsoft-todo/token-cache.json
• 数据不会经由 MAG&Cie 服务器传输
• 可随时在 https://account.live.com/consent/Manage 撤销访问权限
• 清除本地令牌：rm -rf ~/.mcp-microsoft-todo

请求的 Graph 权限：Tasks.ReadWrite、Tasks.ReadWrite.Shared、offline_access。

---

🧑‍💻 开发者设置（派生 / 贡献）

如果你派生此项目，或想使用自己的 Azure AD App Registration 在本地进行开发：

1. Azure AD 应用注册（仅适用于维护者／分叉项目）

1. https://portal.azure.com → Microsoft Entra ID → 应用注册 → 新注册
2. 名称：mcp-microsoft-todo（可自行选择）
3. 支持的帐户类型：任何组织目录中的帐户和个人 Microsoft 帐户
4. 重定向 URI：留空
5. 注册
6. 记下应用程序（客户端）ID
7. 身份验证选项卡 → 允许公共客户端流：是
8. 身份验证选项卡 → 添加平台 → 移动和桌面应用程序 → 勾选 https://login.microsoftonline.com/common/oauth2/nativeclient
9. API 权限选项卡 → 添加权限 → Microsoft Graph → 委派的权限 → 添加 Tasks.ReadWrite、Tasks.ReadWrite.Shared 和 offline_access。如果使用企业租户，请授予管理员同意。

2. 构建和本地身份验证

git clone https://github.com/MAG-Cie/mcp-microsoft-todo
cd mcp-microsoft-todo
npm install
npm run build
export MS_CLIENT_ID="<your-client-id>"   # PowerShell: $env:MS_CLIENT_ID="..."
export MS_TENANT="common"
npm run auth

令牌缓存将写入 ~/.mcp-microsoft-todo/token-cache.json。

3. 配置 Claude Code（本地构建）

# Windows PowerShell
$env:MS_CLIENT_ID="<your-client-id>"
claude mcp add --transport stdio microsoft-todo -- node "C:\path\to\mcp-microsoft-todo\dist\index.js"

# macOS / Linux
export MS_CLIENT_ID="<your-client-id>"
claude mcp add --transport stdio microsoft-todo -- node /path/to/mcp-microsoft-todo/dist/index.js

⚠️ 环境变量必须在进程启动时可见。在 Windows 上使用 fnm 时，请确认启动 claude 的 PowerShell 会话已导出 MS_CLIENT_ID。

4. 运行测试

npm test           # one-shot
npm run test:watch # watch mode

---

⬆️ 从早期版本升级

从	到	所需操作
0.x	0.4.0+	需要重新身份验证：令牌缓存缺少新增的 Tasks.ReadWrite.Shared 范围。运行 rm -rf ~/.mcp-microsoft-todo，然后调用任意工具，通过设备代码重新进行身份验证。
0.x	0.5.0+	不会造成重大变更 — 新增了工具。令牌兼容。
任意版本	1.0.0+	稳定 API 标记。未来的次要版本保证不会更改工具名称、参数或返回格式（精简版 + 详细版）。

---

🗺 路线图

• v0.1 — stdio + 6 个 CRUD 工具
• v0.2 — 可分发的 npm 包，内置客户端 ID
• v0.3 — 重复规则 + 提醒 + 检查清单 + linkedResources + 搜索 + 移动 + summarize_today + 重试／错误处理增强 + vitest 测试 + 精简格式（可选详细格式）
• v0.4 — 自动分页 + $batch 操作 + Tasks.ReadWrite.Shared 范围（读取共享列表）
• v0.5 — 开放扩展 + 跨列表辅助功能（逾期任务、按类别筛选、批量更新）+ iCalendar 导出
• v1.0 — 稳定里程碑：GitHub Actions CI + 扩展测试 + 快照测试 + README 优化

未来可能推出的版本：

• v1.1 — 文件附件（Graph beta）
• v1.2 — 为 summarize_today / search_tasks / list_overdue_tasks 后续增加自动分页
• v2.0 — 用于 Claude.ai 自定义连接器的远程 HTTP/SSE 传输（多用户 OAuth）

---

📄 许可证

MIT — © MAG&Cie