Todoist MCP Server

Todoist MCP Server

一个 MCP（Model Context Protocol）服务，可将 Claude 与 Todoist 连接起来，通过自然语言全面管理任务和项目。

安装

Claude Desktop（一键安装）

1. 从最新版本下载 todoist-mcp.mcpb
2. 双击该文件（或将其拖到 Claude Desktop 中）
3. 根据提示输入你的 Todoist API token
4. 开始对话：“显示我的 Todoist 项目”

Claude Code / 其他 MCP 客户端

claude mcp add todoist -e TODOIST_API_TOKEN=your_token -- npx @greirson/mcp-todoist

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

功能

• 19 个 MCP 工具，全面管理 Todoist
• 任务管理：创建、更新、删除、完成和重新打开任务，并设置优先级、截止日期和标签
• 批量操作：高效处理多个任务
• 子任务：支持完成状态跟踪的分层任务管理
• 项目与分区：全面支持组织管理
• 标签、筛选器、提醒：支持 Pro/Business 功能
• 自然语言：使用 Todoist 的自然语言解析功能快速添加
• 试运行模式：测试操作而不实际更改内容

试运行模式

试运行模式让你可以测试操作和自动化流程，而不会对 Todoist 工作区进行任何实际更改。它非常适合在正式运行前测试、调试、学习 API 或验证自动化脚本。

如何启用试运行模式

在环境配置中添加 DRYRUN=true：

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here",
        "DRYRUN": "true"
      }
    }
  }
}

试运行模式的功能

• 验证操作：使用真实 API 数据验证操作是否能够成功
• 模拟变更：创建、更新、删除和完成操作会进行模拟（不会实际执行）
• 查询真实数据：读取操作（获取任务、项目、标签）会使用真实 API
• 详细日志：通过清晰的 [DRY-RUN] 前缀准确显示将要发生的操作
• 错误检测：捕获与实际执行时相同的错误

使用场景

• 测试自动化流程：在执行前验证复杂的批量操作
• 学习 API：探索功能，不必担心造成不必要的更改
• 调试问题：了解将会执行哪些操作
• 安全试验：尝试新的工作流，而不影响实际任务
• 培训和演示：展示操作的工作方式，而不修改真实数据

使用示例

启用试运行模式后，操作会显示将要发生的情况：

You: "Create a task called 'Test Task' in my Work project"

Response:
[DRY-RUN] Dry-run mode enabled - mutations will be simulated
[DRY-RUN] Would create task: "Test Task" in project 2203306141, section none

Task created successfully (simulated):
ID: 100001
Title: Test Task
Project: Work (2203306141)
Priority: 4 (Normal)

支持的操作

全部 19 个 MCP 工具均支持试运行模式：

• 创建、更新、完成和删除任务
• 子任务操作和层级更改
• 跨多个任务的批量操作
• 创建项目和分区
• 标签管理操作
• 提醒的增删改查操作
• 创建评论

禁用试运行模式

移除 DRYRUN 环境变量或将其设为 false，然后重启 Claude Desktop，即可恢复正常运行模式。

工具概览

该服务提供 19 个 MCP 工具，用于全面管理 Todoist：

如需包含参数和示例的详细工具文档，请参阅 TOOLS_REFERENCE.md。

故障排除

常见问题

“未找到 Todoist 项目”或连接错误：

• 确认 API 令牌正确
• 检查令牌是否已正确设置在 claude_desktop_config.json 中
• 确保令牌两侧没有多余空格或引号

MCP 服务无法加载：

• 确认已全局安装该软件包：npm list -g @greirson/mcp-todoist
• 完全重启 Claude Desktop
• 检查配置文件路径是否适用于你的操作系统
• 尝试使用 mcp-todoist 二进制文件的完整路径：/Users/USERNAME/.npm-global/bin/mcp-todoist

权限错误：

• 在 macOS/Linux 上，你可能需要创建配置目录：mkdir -p ~/.config
• 确保 Claude Desktop 有权读取配置文件

使用示例

项目和分区设置

"Show me all my projects"
"Create a new project called 'Work Tasks'"
"Create a section called 'In Progress' in project 12345"
"Show me sections in the Work Tasks project"

任务创建和管理

"Create task 'Team Meeting' in project 12345"
"Add task 'Review PR' due tomorrow with labels ['Code Review', 'Urgent']"
"Create high priority task with deadline 2024-12-25"
"Update meeting task to be in section 67890"
"Mark the PR review task as complete"

# Task duration for time blocking
"Create task 'Deep work session' with 90 minute duration"
"Update task 'Meeting' to have a 2 day duration"

# Task identification by ID (more reliable than name search)
"Get task with ID 1234567890"
"Update task ID 1234567890 to priority 4"
"Complete task with ID 1234567890"
"Reopen task with ID 1234567890"
"Delete task ID 1234567890"

快速添加

快速添加工具会像 Todoist 应用一样解析自然语言文本，支持在单条命令中使用多项功能：

"Quick add: Buy groceries tomorrow #Shopping @errands p1"
"Quick add: Review PR next Monday #Work @code-review p2 //Check error handling"
"Quick add: Call mom {deadline in 3 days}"
"Quick add: Team meeting today at 2pm #Work @meetings with reminder 1 hour before"

快速添加语法：

• 截止日期：自然语言日期，例如 “tomorrow”、“next Friday”、“Jan 23”、“in 3 days”
• 项目：#ProjectName（项目名称中不能有空格）
• 标签：@label（例如 “@urgent”、“@work”）
• 受分配人：+name（用于共享项目）
• 优先级：p1（紧急）、p2、p3、p4（最低）
• 截止期限：{in 3 days} 或 {March 15}
• 描述：//your description here（必须放在末尾）

子任务管理

"Create subtask 'Prepare agenda' under task 'Team Meeting'"
"Create multiple subtasks for 'Launch Project': 'Design UI', 'Write tests', 'Deploy'"
"Convert task 'Code Review' to a subtask of 'Release v2.0'"
"Promote subtask 'Bug Fix' to a main task"
"Show me the task hierarchy for 'Launch Project' with completion tracking"

批量操作

"Create multiple tasks for project launch: 'Design mockups', 'Write documentation', 'Set up CI/CD'"
"Update all high priority tasks to be due next week"
"Complete all tasks containing 'review' in project 12345"
"Delete all tasks with priority 1 that are overdue"

评论管理

"Add comment 'This needs urgent attention' to task 'Review PR'"
"Add comment with attachment to task 67890"
"Show all comments for task 'Team Meeting'"
"Get comments for project 12345"

标签管理

"Show me all my labels"
"Create a new label called 'Urgent' with red color"
"Update the 'Work' label to be blue and mark as favorite"
"Delete the unused 'Old Project' label"
"Get usage statistics for all my labels"

提醒管理（Pro/Business）

"Show me all my reminders"
"Get reminders for task 'Team Meeting'"
"Create a reminder for task 'Review PR' 30 minutes before due"
"Create an absolute reminder for task 12345 at 2024-12-25T09:00:00Z"
"Update reminder 67890 to trigger at 10:00 instead"
"Delete reminder 67890"

任务发现

"Show all my tasks"
"List high priority tasks due this week"
"Get tasks in project 12345"

测试与验证

"Test my Todoist connection"
"Run basic tests on all Todoist features" // Default: read-only API tests
"Run enhanced tests on all Todoist features" // Full CRUD testing with cleanup
"Benchmark Todoist API performance with 10 iterations"
"Validate that all MCP tools are working correctly"

Dry-Run 测试

启用 Dry-Run 模式（DRYRUN=true）时，请使用普通命令——系统会自动模拟执行：

"Create a test task with priority 1"
"Update all overdue tasks to be due tomorrow"
"Delete all completed tasks in project 12345"
"Create 5 subtasks under task 'Project Planning'"

所有这些操作都会根据真实数据进行验证，但不会进行任何更改。

开发

从源代码构建

# Clone the repository
git clone https://github.com/greirson/mcp-todoist.git

# Navigate to directory
cd mcp-todoist

# Install dependencies
npm install

# Build the project
npm run build

开发命令

# Watch for changes and rebuild
npm run watch

# Run tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

架构

代码库采用清晰的模块化架构，旨在便于维护和扩展：

核心结构

• src/index.ts：主服务入口，负责请求路由
• src/types.ts：TypeScript 类型定义和接口
• src/type-guards.ts：运行时类型验证函数
• src/validation.ts：输入验证和清理
• src/errors.ts：支持结构化处理的自定义错误类型
• src/cache.ts：用于提升性能的内存缓存

模块化工具组织

• src/tools/：按功能组织的领域专用 MCP 工具定义：
  • task-tools.ts - 任务管理（9 个工具）
  • subtask-tools.ts - 子任务操作（5 个工具）
  • project-tools.ts - 项目/分区管理（4 个工具）
  • comment-tools.ts - 评论操作（2 个工具）
  • label-tools.ts - 标签管理（5 个工具）
  • reminder-tools.ts - 提醒操作（4 个工具）
  • test-tools.ts - 测试与验证（3 个工具）
  • index.ts - 集中导出

业务逻辑处理器

• src/handlers/：按领域划分的业务逻辑模块：
  • task-handlers.ts - 任务 CRUD 和批量操作
  • subtask-handlers.ts - 层级任务管理
  • project-handlers.ts - 项目和分区操作
  • comment-handlers.ts - 评论的创建和检索
  • label-handlers.ts - 标签 CRUD 和统计
  • reminder-handlers.ts - 通过 Sync API 执行提醒 CRUD
  • test-handlers.ts - API 测试基础设施
  • test-handlers-enhanced/ - 综合 CRUD 测试框架

实用工具模块

• src/utils/：共享实用函数：
  • api-helpers.ts - API 响应处理工具
  • error-handling.ts - 集中式错误管理
  • parameter-transformer.ts - 将 MCP 参数格式转换为 Todoist SDK 参数格式
  • dry-run-wrapper.ts - Dry-Run 模式实现

更新日志

如需查看所有变更的详细历史记录，请参阅 CHANGELOG.md。

如需迁移指南和不兼容变更的信息，请参阅完整更新日志。

贡献

欢迎贡献！本项目会持续维护，我很感谢社区对改进项目的关注。

关于 AI 辅助贡献的说明

我在自己的开发工作流中使用 Claude Code——AI 辅助编码是构建本项目的常规方式。我鼓励贡献者使用任何能提高效率的工具，包括 AI 编码助手。

不过，AI 工具很容易生成大量看似正确、实则可能引入隐蔽问题的代码：API 映射错误、性能回退、破坏性类型变更，或把无关功能打包在一起导致范围蔓延。我见过一些 PR，只替换了 URL 前缀，却没意识到 API 路径本身也变了；也见过一些 PR，通过每次都获取所有页面来添加分页，却没有保留 limit 参数。

因此，每个 PR 都会接受全面的架构审查。这不是为了把人拒之门外，而是为了维护一个数百人通过 MCP 客户端依赖的代码库。对于看起来未经审查的 AI 输出，我们会详细反馈需要修改的内容及原因，方便你学习并重新提交。

PR 要求

提交拉取请求前，请确保：

1. 每个 PR 只处理一项关注点。 修复一个错误算一个 PR。添加一个新功能算另一个。更新文档又是另一个。如果你的差异涉及 40 个以上互不相关功能的文件，就需要拆分。涉及多个范围的 PR 会被退回并要求拆分。

2. 你理解代码的作用。 如果代码由 AI 工具编写，请在提交前认真审查。你能解释每项更改为何必要吗？如果出了问题，你能调试吗？如果不能，就还没准备好提交。

3. 包含或更新测试。 新功能需要测试。错误修复需要添加能够发现该错误的测试。如果你要更改 API 端点，请验证它们能否正常调用线上 API——不要只因为替换了 URL 就认为已经足够。

4. 完成手动验证。 在本地运行 npm run build 和 npm test。如果你要更改 API 集成代码，请使用自己的 Todoist 账户进行测试（可通过 DRYRUN=true 启用试运行模式）。请在 PR 描述中附上验证证据。

5. CI 必须通过。 CI 检查未通过的 PR 在全部检查通过前不会进入审查。

优质 PR 的标准

• 标题和正文清晰且具有描述性，说明改了什么以及为什么改
• 差异范围明确，易于审查（理想情况是更改少于 200 行）
• 测试能够证明更改有效
• 如果更改影响面向用户的行为，应更新文档
• 不包含无关的格式调整、重构或“顺手改进”

开始贡献

1. Fork 此仓库
2. 从 main 创建功能分支
3. 按照上述指南进行更改
4. 运行 npm run build && npm test && npm run lint 进行验证
5. 提交 PR，并附上清晰的说明

如果你不确定是否需要某项更改，或不知道该如何着手，请先提交 issue 进行讨论。这样可以节省大家的时间，并在编写代码之前就对合适的方案达成共识。

许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

问题与支持

如果你遇到问题或需要支持，请在 GitHub 仓库中提交 issue。