使用说明

Todoist MCP服务器

一个MCP（模型上下文协议）服务器，将Claude与Todoist连接起来，通过自然语言完成任务和项目管理。

快速开始

得到你的 Todoist API令牌

添加到Claude桌面配置：

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

重新启动克劳德桌面
问克劳德： “显示我的Todoist项目”

就是这样！ 现在，您可以直接通过Claude管理Todoist任务。

特性

完成任务管理：使用完整的属性支持创建、读取、更新、删除和完成任务
分层子任务：创建子任务、将任务转换为子任务、升级子任务以及使用完成跟踪查看任务层次结构
批量操作：一次高效地创建、更新、删除或完成多个任务
评论系统：向任务添加评论，并使用附件支持检索评论
标签管理：对标签进行完整的CRUD操作，包括使用统计和分析
项目和部门组织：创建和管理项目和部门
干运行模式：测试自动化和操作，而不进行真正的更改
增强测试：API基本验证和全面的CRUD测试，带有自动清除功能
智能发现：列出项目和部门以查找组织的ID
丰富的任务属性：支持描述、截止日期、优先级、标签、截止日期和项目分配
自然语言接口：使用日常语言管理您的Todoist工作区
性能优化：用于GET操作的30秒缓存，以减少API调用
稳健的错误处理：具有自定义错误类型的结构化错误响应
输入验证：对所有输入进行全面验证和消毒
类型安全：带有运行时类型检查的完整TypeScript实现

安装和设置

通过Smithery安装

通过以下方式自动安装Claude Desktop的mcp todist 铁匠铺:

npx -y @smithery/cli install @greirson/mcp-todoist --client claude

选项1：使用npx（推荐-无需安装）

这是最简单的方法，因为它不需要全局安装任何东西。

步骤1：获取您的Todoist API代币

登录到您的 Todoist帐户
首选设置 → 集成
向下滚动到 开发者 章节
复制您的 API令牌 （确保安全！）

步骤2：配置Claude桌面

将服务器添加到Claude Desktop配置文件中：

在macOS/Linux上：

文件位置： ~/.config/claude_desktop_config.json

在Windows上：

文件位置： %APPDATA%\Claude\claude_desktop_config.json

添加此配置：

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

⚠️ 重要提示： 替换 your_api_token_here 使用步骤1中的实际Todoist API令牌。

选项2：全局npm安装

如果您希望全局安装该软件包：

步骤1：安装软件包

npm install -g @greirson/mcp-todoist

第2步：获取您的Todoist API代币

（与选项1第1步相同）

步骤3：配置Claude桌面

使用此配置进行全局安装：

{
  "mcpServers": {
    "todoist": {
      "command": "mcp-todoist",
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

步骤4:重新启动克劳德桌面

关闭并重新打开Claude Desktop以加载新的MCP服务器。

步骤5：验证安装

在Claude Desktop中，尝试询问：

"Show me my Todoist projects"

您应该看到您的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
详细日志记录：准确显示clear会发生什么 [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)

支持的操作

所有28个MCP工具都支持干运行模式：

任务创建、更新、完成和删除
子任务操作和层次结构更改
跨多个任务的批量操作
项目和部门创建
标签管理操作
评论创建

禁用干运行模式

移除 DRYRUN 环境变量或将其设置为 false，然后重新启动Claude Desktop以返回正常操作模式。

工具概述

服务器提供28个按实体类型组织的工具：

任务管理

Todoist任务创建：创建具有完整属性支持的新任务
Todoist任务获取：按ID检索任务，或结合优先级、标签、自然语言过滤器和严格 due_before/due_after 具有时区感知的窗口的详细信息
Todoist任务更新：更新现有任务（通过ID或部分名称搜索找到）
Todoist任务完成：将任务标记为已完成（通过ID或部分名称搜索找到）
Todoist任务删除：删除任务（通过ID或部分名称搜索找到）

子任务管理

Todoist子任务创建：在具有完全属性支持的父任务下创建子任务
Todoist子任务批量创建：在父任务下高效创建多个子任务
Todoist任务转换为子任务：将现有任务转换为另一个任务的子任务
Todoist子任务推广：将子任务提升为主任务（删除父关系）
Todoist任务层次结构获取：查看包含子任务和完成跟踪的任务层次结构

批量任务操作

Todoist任务批量创建：一次创建多个任务以提高效率
Todoist任务批量更新：根据具有相同严格条件的搜索条件更新多个任务 due_before/due_after 单任务查询使用的筛选
Todoist任务批量删除：根据搜索条件删除多个任务，并进行时区感知的适当比较
Todoist任务批量完成：根据搜索条件完成多个任务，并进行时区感知的适当比较

评论管理

Todoist评论创建：为带有可选文件附件的任务添加注释
Todoist评论获取：检索任务或项目的注释

标签管理

Todoist标签获取：列出所有标签及其ID和颜色
Todoist标签创建：创建具有可选颜色和顺序的新标签
Todoist标签更新：更新现有标签（名称、颜色、顺序、收藏状态）
Todoist标签删除：从工作区中删除标签
Todoist标签统计信息：获取所有标签的详细使用统计数据

项目管理

Todoist项目创建：使用可选颜色和收藏夹状态创建新项目
Todoist项目获取：列出所有项目及其ID和名称

科室管理

Todoist部分创建：在项目中创建部分
Todoist部分获取：列出项目中的部分

测试与验证

Todoist测试连接：验证API令牌并测试连接
Todoist测试所有功能：两种模式-基本（只读API测试）和增强（带清理的完整CRUD测试）
Todoist测试性能：使用可配置迭代对API响应时间进行基准测试

故障排除

常见问题

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

验证您的API令牌是否正确
检查claude_desktop_config.json中的令牌是否设置正确
确保您的令牌周围没有多余的空格或引号

MCP服务器未加载：

确认软件包已全局安装： npm list -g @greirson/mcp-todoist
完全重新启动克劳德桌面
检查配置文件路径是否适合您的操作系统
尝试完整的路径 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 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"
"Delete task ID 1234567890"

子任务管理

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

任务发现

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

干运行测试

启用干运行模式时（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'"

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

工作流入门

1.第一步

"Test my Todoist connection"
"Show me all my Todoist projects"
"Create a new project called 'Claude Integration Test'"

2.基本任务管理

"Create a task 'Try out MCP integration' in my Inbox"
"Add a high priority task 'Review project setup' due tomorrow"
"Show me all my tasks"

3.先进组织

"Create a section called 'In Progress' in my work project"
"Move the setup task to the In Progress section"
"Add a comment 'This is working great!' to my test task"

4.批量操作

"Create multiple tasks: 'Plan meeting agenda', 'Prepare slides', 'Send invites'"
"Complete all tasks containing 'test' in the Claude project"
"Update all high priority tasks to be due next week"

最佳实践

简单开始：从基本任务创建和项目查看开始
使用自然语言：像往常一样提问
试运行测试：在执行之前，使用模拟运行模式验证复杂的操作
利用批量操作：处理多个任务时使用批量工具
先组织：在创建许多任务之前设置项目和部分
定期清理：使用批量操作清理已完成或过时的任务

发展

从源头构建

# 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个工具）
- 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和统计
- 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 -干运行模式实施

更新日志

看更改日志.md 查看所有变化的详细历史。

有关迁移指南和突破性更改，请参阅完整的更改日志。

贡献

欢迎投稿！请随时提交Pull Request。

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

问题和支持

如果您遇到任何问题或需要支持，请在 GitHub存储库.

使用说明

Todoist MCP服务器

快速开始

目录

特性

安装和设置

通过Smithery安装

选项1：使用npx（推荐-无需安装）

步骤1：获取您的Todoist API代币

步骤2：配置Claude桌面

选项2：全局npm安装

步骤1：安装软件包

第2步：获取您的Todoist API代币

步骤3：配置Claude桌面

步骤4:重新启动克劳德桌面

步骤5：验证安装

干运行模式

如何启用模拟运行模式

什么是干跑模式

用例

示例用法

支持的操作

禁用干运行模式

工具概述

任务管理

子任务管理

批量任务操作

评论管理

标签管理

项目管理

科室管理

测试与验证

故障排除

常见问题

使用示例

项目和部门设置

任务创建和管理

子任务管理

批量操作

评论管理

标签管理

任务发现

测试与验证

干运行测试

工作流入门

1.第一步

2.基本任务管理

3.先进组织

4.批量操作

最佳实践

发展

从源头构建

开发命令

建筑

核心结构

模块化工具组织

业务逻辑处理程序

实用模块

更新日志

贡献

许可证

问题和支持

相关 MCP

Flomo笔记服务

GitLab项目管理服务器

Primavera P6 XER文件解析服务器

规范工作流管理工具

3D资产生成服务

文档搜索服务