内容
-v1-mcp-server
一个干净、可靠的 Todoist MCP（模型上下文协议）服务器 - 构建于 **Todoist 统一 API v1** 之上。
## 为什么存在
官方的 Todoist 网页 MCP（`todoist-ai`）在 Anthropic 端存在已知的持久断开连接错误，需要每天重新连接。社区替代么基于已废弃的 REST API v2，要么存在模式验证错误，当 Todoist 返回附加字段时会导致失败，因为其 API 在不断演进。
该服务器：
- 针对 **当前 Todoist API v1**（而非废弃的 v2）
- 使用 **stdio 传输** - 无云依赖，无需每日重新连接
- 使用 **现代 MCP SDK `registerTool()` API**（而非废弃的 `setRequestHandler` 模式）
- **从不强制执行严格的输出模式**，适用于 API 响应 - Todoist 可以自由添加新字段而不会破坏任何内容
- 零 SDK 包装器依赖 - 通过 axios 进行直接 HTTP 调用，因此没有中间库会偏离 API
## 工具（共 31 个）
### 任务
| 工具 | 描述 |
|------|-------------|
| `todoist_get_tasks` | 列出/筛选任务 - 支持ist 的筛选字符串，如 `"today"`、`"overdue"`、`"p1"`、`"#ProjectName"`、`"7 days"` |
| `todoist_get_task` | 通过 ID 获取单个任务 |
| `todoist_create_task` | 创建具有自然语言到期日期的任务（`"tomorrow"`、`"every monday"` 等） |
| `todoist_update_task` | 更新任意字段 `clear_due_date: true` 以删除到期日期 |
| `todoist_complete_task` | 将任务标记为完成 |
| `todoist_reopen_task` | 重新打开已完成的任务 |
| `todoist_delete_task` | 永久删除任务 |
### 项目
| 工具 | 描述 |
|------|-------------|
| `todoist_get_projects` | 列出所有项目 |
| `todoist_get_project` | 通过 ID 获取单个项目 |
| `todoist_create_project` | 创建项目（带有颜色、视图样式、父项目） |
| `todoist_update_project` | 更新项目 |
| `todoist_delete_project` | 永久删除项目及其所有任务 |
### 部分
| 工具 | 描述 |
|------|-------------|
| `todoist_get_sections` | 列出项目内的部分 |
| `todoist_create_section` | 创建部分 |
| `todoist_update_section` | 重命名部分 |
| `todoist_delete_section` | 删除部分 |
### 标签
| 描述 |
|------|-------------|
| `todoist_get_labels` | 列出所有个人标签 |
| `todoist_create_label` | 创建标签 |
| `todoist_update_label` | 更新标签 |
| `todoist_delete_label` | 删除标签 |
### 评论
| 工具 | 描述 |
|------|-------------|
| `todoist_get_comments`出任务或项目的评论（分页） |
| `todoist_get_comment` | 通过 ID 获取单个评论 |
| `todoist_create_comment` | 添加评论到任务或项目（支持 Markdown） |
|ist_update_comment` | 编辑现有评论的内容 |
| `todo_comment` | 永久删除评论 |
### 已完成任务（专业版）
| 工具 | 描述 |
|------|-------------|
| `todoist_get_completed_tasks` | 按完成日期（≤3 个月）或到期日期（≤6 周）查询已完成的任务。版。 |
### 提醒（专业版）
| 工具 | 描述 |
|------|-------------|
| `todoist_get_reminders` | 列出提醒，可选按 `task_id` 筛选。仅专业版。 |
| `todoist_get_reminder` | 通过 ID 获取单个提醒。仅专业版。 |
| `todoist_create_reminder` | 创建相对（`minute_offset` 在到期前）或绝对仅专业版。 |
| `todoist_update` | 更新提醒时间或通知服务。仅专业版。 |
| `todoist_delete_reminder` | 永久删除提醒。仅专业版。 |
> **专业版处理：** 提醒和已完成任务查询需要 Todoist 专业版订阅。如果 API 返回专业版门控错误（HTTP 402 或 403，带有 `premium`/`pro`/`upgrade`/`paid`/`subscription` 关键词），服务器会返回一个干净的消息，解释该功能需要专业版，而不是泄露原始 API 错误。
## 安装
### 1. 获取您的 Todoist API 令牌
前往 **Todoist → 设置 → 集成 → 开发者**，复制您的 API 令牌。
###. 安装和构建
```bash
git clone https://github.com/christulino/todo1-mcp-server
cd todoist-v1-mcp-server
npm install
npm run build
```
### 3. 配置 Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_des.json`:
```json
{
"mcpServers": {
"todoist": {
command": "node",
"args": ["/absolute/path/to/todoist-v1-mcp-server/dist/index.js"],
"env": {
"TODO_TOKEN": "your_api_token_here"
}
}
}
}
```
重启 Claude Desktop应该在已连接的 MCP 服务器中看到 "todoist"。
### 4. 配置 Claude Code（可选）
```bash
claude mcp add todoist -- node /absolute/path/to/todoist-v1-mcp-server/dist/index.js
```
然后设置环境变量：
```bash
export TODOIST_API_TOKEN=your_api_token_here
```
或将其添加到您的 shell 配置文件中。
## 使用示例
连接后，Claude 可以处理自然语言，如：
- _"今天我有什么任务？"_ → 使用 `todoist`，筛选条件为 ` "today"`
- _任务，在下周电话给牙医"_ → 使用 `todoist_create_task`
- _"将牙医任务标记为完成"_ → 使用 `todoist_complete_task`
- _"显示所有逾期的任务"_ → 使用 `todoist_get_tasks`，筛选条件为 `filter:due"`
- _"家居装修的项目"_ → 使用 `todoist_create_project _"我有哪些项目？"_ → 使用 `todoist`
## Todoist 筛选语法
`todoist_get_tasks` 中的 `filter` 参数支持 Todoist 的完整自然语言：
| 筛 含义 |
|--------|---------|
| `today` | 今日到期 |
| `overdue` | 已逾期 |
| `7 days` | 未来 7 天内到期 |
| `p1` | 优先级紧急 |
| `#ProjectName` | 指定项目中的任务 |
| `@labelname` | 带有指定标签的任务 |
| `no due date` | 无到期日期的任务 |
| `today \| overdue` | 今日（用 `\|`） |
| `today & @waiting` | 今日且标签为 'waiting' |
完整筛选文档：https://todoist.com/help/articles/introduction-to-filters
## 需求
- Node.js 18+
- Todoist 账户（免费）
## 开发bash
npm run dev # tsx 监，自动重新加载
npm run build # 编译 TypeScript
npm start # 运行编译后的服务器
```
## 测试
测试套件会调用实时 Todoist API，并运行任务、项目、部分、标签、评论和提醒的完整 CRUD 循环，以及已完成任务查询的只读烟雾测试。提醒和已完成任务测试会检测专业版门控（HTTP 402/403），并在帐户为免费版时进行干净地报告。
```bash
TODOIST_API_TOKEN=your_token npm test
API 令牌位于 **Todoist → 设置 → 集成 → 开发者** - 与您在 `claude_desktop` 中放置的令牌相同。
## 贡献
欢迎提交 PR。目标是保持最小化、正确的实现，并与 API v1 保持同步。优先级：
1. 正确性高于聪明性
2. 宽容的输出处理（从不拒绝未知的 API 字段）
3. 有帮助的错误消息，告诉您出了什么问题以及如何修复
## 许可证
MIT
