Scan to join WeChat groupREADME
🚀 增强版Todoist MCP服务器扩展
这是一个全面的MCP（模型上下文协议）服务器实现，可实现Claude与Todoist的全面集成。此扩展版本由kydycode从原始的@abhiz123/todoist-mcp-server派生而来，并进行了增强。它包含了额外的功能、改进的兼容性，并且使用完整的Todoist API和最新的MCP SDK（@doist/todoist-api-typescript@4.0.4）增强了功能。
🚀 快速开始
本地开发设置
# 克隆扩展版本仓库
git clone https://github.com/kydycode/todoist-mcp-server-ext.git
cd todoist-mcp-server-ext
# 安装依赖
npm install
# 构建项目
npm run build
获取Todoist API令牌
- 登录你的Todoist账户。
- 导航到设置 → 集成 → 开发者。
- 复制你的API令牌。
在Claude桌面版中使用
添加到你的claude_desktop_config.json文件中：
选项1：运行本地构建版本
{
"mcpServers": {
"todoist-mcp-server": {
"command": "node",
"args": ["/path/to/your/todoist-mcp-server-ext/dist/index.js"],
"env": {
"TODOIST_API_TOKEN": "your_api_token_here"
}
}
}
}
选项2：通过npm/npx运行（推荐用于已发布版本）
{
"mcpServers": {
"todoist-mcp-server": {
"command": "npx",
"args": ["-y", "@kydycode/todoist-mcp-server-ext@latest"],
"env": {
"TODOIST_API_TOKEN": "your_api_token_here"
}
}
}
}
选项3：先全局安装
# 全局安装扩展版本
npm install -g @kydycode/todoist-mcp-server-ext@latest
# 然后在Claude桌面版配置中使用
{
"mcpServers": {
"todoist-mcp-server": {
"command": "todoist-mcp-server-ext",
"env": {
"TODOIST_API_TOKEN": "your_api_token_here"
}
}
}
}
✨ 主要特性
🔧 技术改进
- 更新的Todoist SDK：现在使用
@doist/todoist-api-typescript@4.0.4。 - 更新的MCP SDK兼容性：与MCP SDK 0.5.0兼容。
- 增强的错误处理：全面的错误处理，带有详细的错误消息。
- 改进的TypeScript支持：更好的类型安全性和兼容性。
- 优化的API使用：高效使用Todoist API，包括用于强大搜索的
getTasksByFilter和用于语义任务移动的moveTasks。 - 更好的响应格式：增强的任务、项目和标签格式，提高可读性，包括搜索结果中的项目名称。
✨ 增强的任务管理（10个工具）
- 基于ID的直接操作：使用任务ID进行高效的任务操作。
- 全面的任务创建：支持子任务、标签、项目、部分、优先级。
- 快速添加集成：使用Todoist的快速添加功能以自然语言创建任务。
- 高级任务搜索：使用Todoist的过滤引擎进行强大的关键字搜索（
search: your query）。 - 任务移动功能：在项目、部分之间移动任务，或将其设为子任务。
- 任务状态管理：完成、重新打开和管理任务生命周期。
- 详细的任务输出：搜索和获取任务操作返回更多任务详细信息。
🗂️ 完整的项目管理（5个工具）
- 完整的项目CRUD操作：使用所有属性创建、读取、更新、删除项目。
- 子项目支持：创建分层项目结构。
- 项目自定义：设置颜色、收藏夹、视图样式（列表/看板）。
- 增强的项目列表：改进的项目检索，支持分页和详细格式。
📋 部分管理（4个工具）
- 完整的部分操作：创建、读取、更新、删除部分。
- 特定项目的部分：过滤和管理项目内的部分。
- 部分组织：正确的排序和结构管理。
🏷️ 标签管理（5个工具）
- 完整的标签CRUD操作：创建、读取、更新、删除标签。
- 标签自定义：设置名称、颜色、收藏夹、顺序。
- 分页标签列表：高效检索所有标签。
💬 评论管理（5个工具）
- 完整的评论CRUD操作：在任务和项目上创建、读取、更新、删除评论。
- 附件支持：在评论中添加带有元数据的文件附件。
- 灵活的目标设置：评论可以附加到任务或项目。
- 分页评论检索：高效浏览评论线程。
🛠️ 可用工具（共29个）
任务操作（10个工具）
| 工具 | 详情 |
| ---- | ---- |
| todoist_create_task | 使用所有选项（子任务、标签、项目、部分、优先级）创建任务。 |
| todoist_quick_add_task | 使用Todoist的快速添加语法以自然语言创建任务。 |
| todoist_get_tasks | 使用过滤（项目、部分、父任务、标签、ID）和分页检索任务。 |
| todoist_get_task | 通过任务ID获取特定任务，并返回详细信息。 |
| todoist_update_task | 更新任务属性（内容、描述、截止日期、优先级、标签）。 |
| todoist_delete_task | 通过任务ID删除任务。 |
| todoist_complete_task | 标记任务为已完成。 |
| todoist_reopen_task | 重新打开已完成的任务。 |
| todoist_search_tasks | 使用Todoist的过滤引擎搜索任务（例如，search: keyword）。 |
| todoist_move_task | 将任务移动到不同的项目、部分，或将其设为子任务。 |
项目操作（5个工具）
| 工具 | 详情 |
| ---- | ---- |
| todoist_get_projects | 列出所有活动项目，支持分页。 |
| todoist_get_project | 通过项目ID获取特定项目。 |
| todoist_create_project | 创建新项目（名称、颜色、收藏夹、视图样式、子项目）。 |
| todoist_update_project | 更新项目属性。 |
| todoist_delete_project | 通过项目ID删除项目。 |
部分操作（4个工具）
| 工具 | 详情 |
| ---- | ---- |
| todoist_get_sections | 列出部分（所有部分或特定项目的部分）。 |
| todoist_create_section | 在项目中创建部分（名称、项目、排序）。 |
| todoist_update_section | 更新部分名称。 |
| todoist_delete_section | 通过部分ID删除部分。 |
标签操作（5个工具）
| 工具 | 详情 |
| ---- | ---- |
| todoist_create_label | 创建新标签（名称、颜色、收藏夹、顺序）。 |
| todoist_get_label | 通过标签ID获取特定标签。 |
| todoist_get_labels | 列出所有标签，支持分页。 |
| todoist_update_label | 通过标签ID更新现有标签（名称、颜色、收藏夹、顺序）。 |
| todoist_delete_label | 通过标签ID删除标签。 |
评论操作（5个工具）
| 工具 | 详情 |
| ---- | ---- |
| todoist_create_comment | 在任务或项目上创建新评论（支持附件）。 |
| todoist_get_comment | 通过评论ID获取特定评论。 |
| todoist_get_comments | 获取任务或项目的评论，支持分页。 |
| todoist_update_comment | 通过评论ID更新现有评论。 |
| todoist_delete_comment | 通过评论ID删除评论。 |
💻 使用示例
🎯 高级任务创建与管理
"Create task 'Team Meeting @Tomorrow #Work p1'"
"Add task 'Fix critical bug +KydyCode @DevProject L:Urgent L:Backend'"
"Quick add: 'Buy milk tomorrow at 2pm #shopping !p1'"
"Move task with ID {task_id} to project {project_id}"
"Search tasks: search: API deployment"
🗂️ 项目、部分、标签和评论管理
"List all my projects"
"Create project 'Q2 Planning' color:blue favorite:true view:board"
"Get sections for project {project_id}"
"Create label 'HighPriority' color:red isFavorite:true"
"List all labels"
"Add comment 'Great progress on this task!' to task {task_id}"
"Get all comments for project {project_id}"
"Update comment {comment_id} with new content"
🆚 扩展版本与原始版本对比
| 特性 | 原始版本 | 扩展版本 (@kydycode/todoist-mcp-server-ext) |
| ---- | ---- | ---- |
| Todoist SDK版本 | 旧版本 | ✅ @doist/todoist-api-typescript@4.0.4 |
| MCP SDK兼容性 | 旧版本 | ✅ 最新的MCP SDK 0.5.0+ |
| 错误处理 | 基本处理 | ✅ 全面处理，带有详细消息 |
| TypeScript支持 | 有限支持 | ✅ 完整的类型安全性 |
| 任务操作 | 基于搜索，功能有限 | ✅ 10个工具：基于ID的直接操作、moveTasks、强大的搜索、快速添加、类似完整的CRUD操作 |
| 项目管理 | 有限 | ✅ 5个工具：完整的CRUD操作、子项目、分页 |
| 部分管理 | 基本 | ✅ 4个工具：完整的部分操作 |
| 标签管理 | 不可用 | ✅ 5个工具：完整的CRUD操作、分页 |
| 评论管理 | 不可用 | ✅ 5个工具：完整的CRUD操作、附件、分页 |
| API参数处理 | 不一致 | ✅ 正确的参数验证 |
| 响应格式 | 基本 | ✅ 增强的可读性，更多详细信息 |
| 构建系统 | 有问题 | ✅ 干净的编译 |
| 搜索功能 | 基本的本地过滤 | ✅ 强大的getTasksByFilter（Todoist引擎） |
🔧 技术细节
项目结构
src/
├── index.ts # 包含所有工具的主服务器实现
package.json # 依赖和脚本
tsconfig.json # TypeScript配置
README.md # 本文件
local-instructions.md # 个人发布指南
LICENSE
.gitignore
dist/ # 编译后的JavaScript输出（运行`npm run build`后）
├── index.js
└── index.d.ts
从源代码构建
# 安装依赖
npm install
# 构建TypeScript
npm run build
# 测试服务器（需要TODOIST_API_TOKEN）
# 示例：设置令牌并发送列出工具的请求
export TODOIST_API_TOKEN="your_actual_todoist_api_token"
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | node dist/index.js
开发脚本
npm run build # 编译TypeScript并使输出可执行
npm run watch # 监视更改并重新构建（不使输出可执行）
npm run prepare # 预发布构建（运行build）
🤝 贡献
欢迎贡献！此扩展版本接受以下方面的贡献：
- 额外的Todoist API端点
- 增强的错误处理和验证
- 性能优化
- 文档改进
- 错误修复和兼容性更新
请将问题和拉取请求提交到扩展版本仓库。
📄 许可证
本项目根据MIT许可证授权 - 详情请参阅LICENSE文件。
🙏 致谢
🐛 问题与支持
- 扩展版本问题：GitHub问题
- 原始仓库：abhiz123/todoist-mcp-server