内容
# 微软待办事项 MCP 服务器
[](https://github.com/jordanburke/microsoft-todo-mcp-server/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/microsoft-todo-mcp-server)
一个模型上下文协议（MCP）服务器，允许Claude和Cursor等AI助手通过Microsoft Graph API与微软待办事项交互。该服务通过安全的OAuth 2.0身份验证流程提供全面的任务管理功能。
## 功能
- **15 个 MCP 工具**：完整的任务管理功能，包括列表、任务、检查清单项和组织功能
- **无缝身份验证**：自动令牌刷新，无需手动干预
- **OAuth 2.0 身份验证**：安全的身份验证，自动刷新令牌
- **Microsoft Graph API 集成**：与微软官方API直接集成
- **多租户支持**：适用于个人、工作和学校微软账户
- **TypeScript**：完全类型化，以提高可靠性和开发人员体验
- **ESM 模块**：现代JavaScript模块系统
## 先决条件
- Node.js 16 或更高版本（已测试 Node.js 18.x、20.x 和 22.x）
- pnpm 包管理器
- 微软账户（个人、工作或学校账户）
- Azure 应用注册（参见下面的设置）
## 安装
### 选项 1：全局安装（推荐）
```bash
# 使用 npm 全局安装
npm install -g microsoft-todo-mcp-server
# 或使用 pnpm
pnpm install -g microsoft-todo-mcp-server
# 或直接使用 npx（无需安装）
npx microsoft-todo-mcp-server
```
该包提供了三个命令别名：
- `microsoft-todo-mcp-server` - 完整包名
- `mstodo` - MCP 服务器的简短别名
- `mstodo-config` - 配置助手工具
### 选项 2：克隆并本地运行
```bash
git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git
cd microsoft-todo-mcp-server
pnpm install
pnpm run build
```
## Azure 应用注册
1. 进入 [Azure 门户](https://portal.azure.com)
2. 导航到“应用注册”并创建新的注册
3. 为您的应用程序命名（例如“待办事项 MCP”）
4. 对于“支持的帐户类型”，根据您的需求选择以下选项之一：
- **仅此组织目录中的帐户（单个租户）** - 在单个组织中使用
- **任何组织目录中的帐户（任何 Azure AD 目录 - 多租户）** - 跨多个组织使用
- **任何组织目录和个人微软帐户** - 适用于工作帐户和个人帐户
5. 将重定向 URI 设置为 `http://localhost:3000/callback`
6. 创建应用后，进入“证书和机密”并创建一个新的客户端机密
7. 进入“API 权限”并添加以下权限：
- Microsoft Graph > 委托权限：
- Tasks.Read
- Tasks.ReadWrite
- User.Read
8. 为这些权限单击“授予管理员同意”
## 配置
### 环境设置
在项目根目录中创建一个 `.env` 文件（身份验证所需）：
```env
CLIENT_ID=您的客户端 ID
CLIENT_SECRET=您的客户端机密
TENANT_ID=您的租户设置
REDIRECT_URI=http://localhost:3000/callback
```
### TENANT_ID 选项
- `organizations` - 用于多租户组织帐户（默认如果未指定）
- `consumers` - 仅用于个人微软帐户
- `common` - 适用于组织和个人帐户
- `您的特定租户 ID` - 用于单租户配置
**示例：**
```env
# 用于多租户组织帐户（默认）
TENANT_ID=organizations
# 用于个人微软帐户
TENANT_ID=consumers
# 适用于组织和个人帐户
TENANT_ID=common
# 用于特定组织租户
TENANT_ID=00000000-0000-0000-0000-000000000000
```
###令牌存储
服务器在 `tokens.json` 中存储身份验证令牌，并在过期前 5 分钟自动刷新。您可以覆盖令牌文件位置：
```bash
# 使用环境变量
export MSTODO_TOKEN_FILE=/path/to/custom/tokens.json
# 或直接传递令牌
export MS_TODO_ACCESS_TOKEN=您的访问令牌
export MS_TODO_REFRESH_TOKEN=您的刷新令牌
```
## 用法
### 完整的设置工作流程
#### 步骤 1：与微软身份验证
```bash
# 如果已全局安装
git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git
cd microsoft-todo-mcp-server
pnpm install
pnpm run auth
# 或如果本地运行
pnpm run auth
```
这将打开一个浏览器窗口用于微软身份验证，并创建一个 `tokens.json` 文件。
#### 步骤 2：创建 MCP 配置
```bash
# 生成 MCP 配置文件
pnpm run create-config
# 或使用全局助手（如果已全局安装）
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`
```json
{
"mcpServers": {
"microsoftTodo": {
"command": "npx",
"args": ["--yes", "microsoft-todo-mcp-server"],
"env": {
"MS_TODO_ACCESS_TOKEN": "您的访问令牌",
"MS_TODO_REFRESH_TOKEN": "您的刷新令牌"
}
}
}
}
```
**适用于 Cursor：**
```bash
# 复制到 Cursor 的全局配置
cp mcp.json ~/.cursor/mcp-servers.json
```
### 可用的脚本
```bash
# 开发和构建
pnpm run build # 将 TypeScript 构建为 JavaScript
pnpm run dev # 构建并运行 CLI
# 运行服务器
pnpm start # 直接运行 MCP 服务器
pnpm run cli # 通过 CLI 包装器运行 MCP 服务器
npx microsoft-todo-mcp-server # 运行全局安装的版本
# 身份验证和配置
pnpm run auth # 启动 OAuth 身份验证服务器
pnpm run create-config # 从 tokens.json 生成 mcp.json
# 代码质量
pnpm run format # 使用 Prettier 格式化代码
pnpm run format:check # 检查代码格式化
pnpm run lint # 运行 linting 检查
pnpm run typecheck # TypeScript 类型检查
```
## MCP 工具
服务器提供 13 个工具用于全面的微软待办事项管理：
### 身份验证
- **`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 协议的核心服务器
- **CLI 包装器** (`src/cli.ts`) - 具有令牌管理的可执行入口点
- **身份验证服务器** (`src/auth-server.ts`) - 用于 OAuth 2.0 流的 Express 服务器
- **配置生成器** (`src/create-mcp-config.ts`) - 帮助程序，用于创建 MCP 配置
### 技术细节
- **Microsoft Graph API**：使用 v1.0 端点
- **身份验证**：MSAL（Microsoft Authentication Library）与 PKCE 流
- **令牌管理**：令牌在过期前 5 分钟自动刷新
- **构建系统**：tsup 用于快速 TypeScript 编译
- **模块系统**：ESM（ECMAScript 模块）
## 限制和已知问题
### 个人微软账户
- **MailboxNotEnabledForRESTAPI 错误**：个人微软账户（outlook.com、hotmail.com、live.com）对通过 Microsoft Graph 的 To Do API 访问有限
- 这是微软的服务限制，而不是此应用程序的问题
- 工作/学校账户具有完全的 API 访问权限
### API 限制
- 根据微软的政策，速率限制适用
- 一些功能可能不适用于个人账户
- 共享列表的功能有限
## 故障排除
### 身份验证问题
**令牌获取失败**
- 验证 `.env` 文件中的 `CLIENT_ID` 、 `CLIENT_SECRET` 和 `TENANT_ID`
- 确保重定向 URI 完全匹配： `http://localhost:3000/callback`
- 检查 Azure 应用权限是否已授予管理员同意
**权限问题**
- 确保已添加所有必需的 Graph API 权限并获得同意
- 对于组织帐户，可能需要管理员同意
### 帐户类型配置
**工作/学校账户**
```env
TENANT_ID=organizations # 多租户
# 或使用您的特定租户 ID
```
**个人账户**
```env
TENANT_ID=consumers # 仅个人账户
# 或 TENANT_ID=common 同时适用于两种类型
```
### 调试
**检查身份验证状态：**
```bash
# 使用 MCP 工具
# 在您的 AI 助手中： “检查身份验证状态”
# 或直接检查令牌
cat tokens.json | jq '.expiresAt'
# 将时间戳转换为可读日期
date -d @$(($(cat tokens.json | jq -r '.expiresAt') / 1000))
```
**启用详细日志记录：**
```bash
# 服务器将日志记录到 stderr 进行调试
mstodo 2> debug.log
```
## 贡献
欢迎贡献！请：
1. 复刻仓库
2. 创建一个功能分支
3. 在提交之前运行 `pnpm run lint` 和 `pnpm run typecheck`
4. 提交拉取请求
## 许可证
MIT 许可证 - 有关详细信息，请参见 [LICENSE](LICENSE) 文件
## 致谢
- [@jhirono/todomcp](https://github.com/jhirono/todomcp) 的复刻
- 构建在 [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk) 之上
- 使用 [Microsoft Graph API](https://developer.microsoft.com/en-us/graph)
## 支持
- [GitHub 问题](https://github.com/jordanburke/microsoft-todo-mcp-server/issues)
- [npm 包](https://www.npmjs.com/package/microsoft-todo-mcp-server)
