金大哥 - todoist-mcp-server-ext MCP 详情

article

README

🚀 增强版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文件。

🙏 致谢

扩展版本：kydycode - 增强功能和兼容性
原始创建者：@abhiz123 - 初始的Todoist MCP服务器实现
MCP协议：模型上下文协议，由Anthropic提供

🐛 问题与支持

扩展版本问题：GitHub问题
原始仓库：abhiz123/todoist-mcp-server

🔗 相关链接

扩展版本仓库：kydycode/todoist-mcp-server-ext
NPM包：@kydycode/todoist-mcp-server-ext
原始仓库：abhiz123/todoist-mcp-server
Todoist API文档
模型上下文协议
Claude桌面版

todoist-mcp-server-ext