Todoist MCP Server Ext

🚀 增强版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令牌

1. 登录你的Todoist账户。
2. 导航到设置 → 集成 → 开发者。
3. 复制你的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个工具）

项目操作（5个工具）

部分操作（4个工具）

标签操作（5个工具）

评论操作（5个工具）

💻 使用示例

🎯 高级任务创建与管理

"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"

🆚 扩展版本与原始版本对比

🔧 技术细节

项目结构

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桌面版