microsoft-todo-mcp-server

Microsoft To Do MCP

一个 Model Context Protocol（MCP）服务，可让 Claude 和 Cursor 等 AI 助手通过 Microsoft Graph API 与 Microsoft To Do 交互。此服务通过安全的 OAuth 2.0 身份验证流程，提供全面的任务管理功能。

功能

• 15 个 MCP 工具：完整的任务管理功能，包括列表、任务、清单项目和组织功能
• 无缝身份验证：自动刷新令牌，无需手动干预
• OAuth 2.0 身份验证：安全的身份验证，并自动刷新令牌
• Microsoft Graph API 集成：直接集成 Microsoft 官方 API
• 多租户支持：支持个人、工作和学校 Microsoft 账户
• TypeScript：提供完整的类型定义，提升可靠性和开发体验
• ESM 模块：现代 JavaScript 模块系统

前提条件

• Node.js 16 或更高版本（已在 Node.js 18.x、20.x 和 22.x 上测试）
• pnpm 包管理器
• Microsoft 账户（个人、工作或学校）
• Azure 应用注册（请参阅下方的设置说明）

安装

选项 1：全局安装（推荐）

# Install globally using npm
npm install -g microsoft-todo-mcp-server

# Or using pnpm
pnpm install -g microsoft-todo-mcp-server

# Or run directly with npx (no installation)
npx microsoft-todo-mcp-server

此软件包提供三个命令别名：

• microsoft-todo-mcp-server - 完整的软件包名称
• mstodo - MCP 服务的短别名
• mstodo-config - 配置辅助工具

选项 2：克隆并在本地运行

git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git
cd microsoft-todo-mcp-server
pnpm install
pnpm run build

Azure 应用注册

1. 前往 Azure 门户
2. 转到“应用注册”并创建新的注册
3. 为应用命名（例如“ To Do MCP”）
4. 对于“支持的账户类型”，请根据需要选择以下一项：
   • 仅此组织目录中的账户（单租户） - 在单个组织内使用
   • 任何组织目录中的账户（任何 Azure AD 目录 - 多租户） - 在多个组织间使用
   • 任何组织目录中的账户和个人 Microsoft 账户 - 用于工作账户和个人账户
5. 将重定向 URI 设置为 http://localhost:3000/callback
6. 创建应用后，前往“证书和机密”并创建新的客户端密钥
7. 前往“API 权限”并添加以下权限：
   • Microsoft Graph > 委派权限：
     • Tasks.Read
     • Tasks.ReadWrite
     • User.Read
8. 点击“授予管理员同意”以授予这些权限

配置

环境设置

在项目根目录中创建 .env 文件（身份验证必需）：

CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
TENANT_ID=your_tenant_setting
REDIRECT_URI=http://localhost:3000/callback

TENANT_ID 选项

• organizations - 用于多租户组织账户（未指定时的默认值）
• consumers - 仅用于个人 Microsoft 账户
• common - 用于组织账户和个人账户
• your-specific-tenant-id - 用于单租户配置

示例：

# For multi-tenant organizational accounts (default)
TENANT_ID=organizations

# For personal Microsoft accounts
TENANT_ID=consumers

# For both organizational and personal accounts
TENANT_ID=common

# For a specific organization tenant
TENANT_ID=00000000-0000-0000-0000-000000000000

令牌存储

服务会将身份验证令牌存储在 tokens.json 中，并按以下顺序检查三个位置：

1. 如果已设置，则使用 MSTODO_TOKEN_FILE
2. 每用户配置目录——~/.config/microsoft-todo-mcp/tokens.json，或 Windows 上的 %APPDATA%\microsoft-todo-mcp\tokens.json
3. 工作目录中的 tokens.json；首次读取时会将其迁移到 (1) 或 (2) 当前生效的位置

# Override the location
export MSTODO_TOKEN_FILE=/path/to/custom/tokens.json

你也可以直接提供令牌，其优先级高于文件中的令牌：

export MS_TODO_ACCESS_TOKEN=your_access_token
export MS_TODO_REFRESH_TOKEN=your_refresh_token

这两个环境变量只是初始值，并非实时存储——令牌续期时，程序不会改写你的环境变量。续期后的令牌会在本次会话剩余时间内使用，并写入令牌文件，之后程序不会再读取这两个环境变量。

具体如何得知令牌过期时间，取决于你的账户类型。工作和学校账户使用 JWT 访问令牌，因此服务会从中读取实际过期时间，并提前 5 分钟续期。个人账户使用不透明令牌，无法从中读取过期时间，因此服务会从首次获取该令牌时起，按 1 小时估算。无论哪种情况，续期都需要 CLIENT_ID 和 CLIENT_SECRET；如果没有这些值，服务就无法刷新令牌，提供的令牌过期后，调用便会开始失败。

用法

完整设置流程

第 1 步：通过 Microsoft 进行身份验证

# If installed globally
git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git
cd microsoft-todo-mcp-server
pnpm install
pnpm run auth

# Or if running locally
pnpm run auth

这会打开 Microsoft 身份验证浏览器窗口，并创建一个 tokens.json 文件。

第 2 步：创建 MCP 配置

# Generate MCP configuration file
pnpm run create-config

# Or use the global helper (if installed globally)
mstodo-config

这会创建一个包含身份验证令牌的 mcp.json 文件。

第 3 步：配置你的 AI 助手

对于 Claude Desktop：

将以下内容添加到你的配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "microsoftTodo": {
      "command": "npx",
      "args": ["--yes", "microsoft-todo-mcp-server"],
      "env": {
        "MS_TODO_ACCESS_TOKEN": "your_access_token",
        "MS_TODO_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

对于 Cursor：

# Copy to Cursor's global configuration
cp mcp.json ~/.cursor/mcp-servers.json

可用脚本

# Development & Building
pnpm run build        # Build TypeScript to JavaScript
pnpm run dev          # Build and run CLI in one command

# Running the Server
pnpm start            # Run MCP server directly
pnpm run cli          # Run MCP server via CLI wrapper
npx microsoft-todo-mcp-server  # Run globally installed version

# Authentication & Configuration
pnpm run auth         # Start OAuth authentication server
pnpm run create-config # Generate mcp.json from tokens.json

# Code Quality
pnpm run format       # Format code with Prettier
pnpm run format:check # Check code formatting
pnpm run lint         # Run linting checks
pnpm run typecheck    # TypeScript type checking

MCP 工具

该服务提供 13 个工具，用于全面管理 Microsoft To Do：

身份验证

• auth-status - 检查身份验证状态、令牌过期时间和账户类型

任务列表（顶级容器）

• get-task-lists - 获取所有任务列表及其元数据（默认列表、共享列表等）
• create-task-list - 创建新的任务列表
• update-task-list - 重命名现有任务列表
• delete-task-list - 删除任务列表及其所有内容

任务（主要待办事项）

• get-tasks - 从列表中获取任务，支持筛选、排序和分页
  • 支持 OData 查询参数：$filter、$select、$orderby、$top、$skip、$count
• create-task - 创建任务，支持完整属性
  • 标题、描述、截止日期、开始日期、重要性、提醒、状态、类别
• update-task - 更新任意任务属性
• delete-task - 删除任务及其所有清单项

清单项（子任务）

• get-checklist-items - 获取指定任务的子任务
• create-checklist-item - 向任务添加新的子任务
• update-checklist-item - 更新子任务文本或完成状态
• delete-checklist-item - 移除指定子任务

架构

项目结构

• MCP 服务（src/todo-index.ts）- 实现 MCP 协议的核心服务
• 命令行包装器（src/cli.ts）- 带有令牌管理功能的可执行入口
• 身份验证服务（src/auth-server.ts）- 用于 OAuth 2.0 流程的 Express 服务
• 配置生成器（src/create-mcp-config.ts）- 用于创建 MCP 配置的辅助工具

技术详情

• Microsoft Graph API：使用 v1.0 端点
• 身份验证：使用 PKCE 流程的 MSAL（Microsoft Authentication Library）
• 令牌管理：在令牌过期前 5 分钟自动刷新
• 构建系统：使用 ts-builds（tsdown）进行快速 TypeScript 编译
• 模块系统：ESM（ECMAScript 模块）

限制和已知问题

个人 Microsoft 帐户

• MailboxNotEnabledForRESTAPI Error：个人 Microsoft 帐户（outlook.com、hotmail.com、live.com）通过 Microsoft Graph 访问 To Do API 的权限有限
• 这是 Microsoft 服务的限制，并非此应用的问题
• 工作或学校帐户拥有完整的 API 访问权限

API 限制

• 速率限制遵循 Microsoft 的相关政策
• 个人帐户可能无法使用某些功能
• 共享列表的功能有限

故障排除

身份验证问题

令牌获取失败

• 检查 .env 文件中的 CLIENT_ID、CLIENT_SECRET 和 TENANT_ID
• 确保重定向 URI 完全匹配：http://localhost:3000/callback
• 检查 Azure 应用权限是否已授予并获得管理员同意

权限问题

• 确保已添加所有必需的 Graph API 权限并获得同意
• 对于组织帐户，可能需要管理员同意

帐户类型配置

工作或学校帐户

TENANT_ID=organizations  # Multi-tenant
# Or use your specific tenant ID

个人帐户

TENANT_ID=consumers  # Personal only
# Or TENANT_ID=common for both types

调试

检查身份验证状态：

# Using the MCP tool
# In your AI assistant: "Check auth status"

# Or examine tokens directly
cat tokens.json | jq '.expiresAt'

# Convert timestamp to readable date
date -d @$(($(cat tokens.json | jq -r '.expiresAt') / 1000))

启用详细日志记录：

# The server logs to stderr for debugging
mstodo 2> debug.log

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 提交前运行 pnpm run lint 和 pnpm run typecheck
4. 提交拉取请求

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

致谢

• Fork 自 @jhirono/todomcp
• 基于 Model Context Protocol SDK 构建
• 使用 Microsoft Graph API

支持

• GitHub Issues
• npm Package