🚀 增强版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
{
"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
npm run build
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
npm run watch
npm run prepare
🤝 贡献
欢迎贡献！此扩展版本接受以下方面的贡献：
- 额外的Todoist API端点
- 增强的错误处理和验证
- 性能优化
- 文档改进
- 错误修复和兼容性更新
请将问题和拉取请求提交到扩展版本仓库。
📄 许可证
本项目根据MIT许可证授权 - 详情请参阅LICENSE文件。
🙏 致谢
🐛 问题与支持
🔗 相关链接
