STARWARCLOUD STARWAR.AI
返回市场
任务管理器

任务管理器

作者：greirson46 星标更新：2025-11-01
安装使用来源：spider==github.com

项目介绍

Todoist MCP Server

smithery 徽章

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

<a href="https://glama.ai/mcp/servers/@greirson/mcp-todoist"> <img width="380" height="200" src="https://gips0.baidu.com/it/u=762031313,3111290978&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Todoist Server MCP服务器" /> </a>

快速开始

  1. 获取你的Todoist API令牌
  2. 添加到Claude Desktop配置中： 
    {
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}
  3. 重启Claude Desktop
  4. 向Claude提问："显示我的Todoist项目"

**就这样！**现在你可以通过Claude直接管理你的Todoist任务了。

目录

功能

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

安装与设置

通过Smithery安装

要通过Smithery自动为Claude Desktop安装mcp-todoist：

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

方案1：使用npx（推荐 - 不需要安装）

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

步骤1：获取你的Todoist API令牌

  1. 登录到你的Todoist账户
  2. 前往设置 → 集成
  3. 滚动到开发者部分
  4. 复制你的API令牌（请妥善保管！）

步骤2：配置Claude Desktop

将服务器添加到你的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 Desktop

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

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

步骤4：重启Claude Desktop

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

步骤5：验证安装

在Claude Desktop中尝试询问：

"显示我的Todoist项目"

你应该能看到你的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：探索功能而不担心做出不必要的更改
  • 调试问题：理解会执行哪些操作
  • 安全实验：尝试新工作流而不影响实际任务
  • 培训和演示：展示操作如何工作而不修改真实数据

示例用法

启用干运行模式后，操作会显示会发生什么：

你： "在我的工作项目中创建一个名为'Test Task'的任务"

响应：
[DRY-RUN] 干运行模式已启用 - 变更将被模拟
[DRY-RUN] 将创建任务："Test Task" 在项目2203306141，部分无

任务创建成功（模拟）：
ID：100001
标题：Test Task
项目：工作（2203306141）
优先级：4（普通）

支持的操作

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

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

禁用干运行模式

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

工具概述

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

任务管理

  • Todoist Task Create：创建具有完整属性支持的新任务
  • Todoist Task Get：通过ID检索任务，或结合优先级、标签、自然语言过滤器以及严格的due_before/due_after窗口和时区感知到期详情
  • Todoist Task Update：更新现有任务（通过ID或部分名称搜索找到）
  • Todoist Task Complete：标记任务为已完成（通过ID或部分名称搜索找到）
  • Todoist Task Delete：删除任务（通过ID或部分名称搜索找到）

子任务管理

  • Todoist Subtask Create：在父任务下创建具有完整属性支持的子任务
  • Todoist Subtasks Bulk Create：高效地在父任务下创建多个子任务
  • Todoist Task Convert to Subtask：将现有任务转换为另一个任务的子任务
  • Todoist Subtask Promote：提升子任务为主任务（移除父关系）
  • Todoist Task Hierarchy Get：查看带有子任务和完成跟踪的任务层次结构

批量任务操作

  • Todoist Tasks Bulk Create：一次创建多个任务以提高效率
  • Todoist Tasks Bulk Update：根据搜索条件更新多个任务，使用单任务查询中的相同严格due_before/due_after过滤
  • Todoist Tasks Bulk Delete：根据搜索条件删除多个任务，使用时区感知到期比较
  • Todoist Tasks Bulk Complete：根据搜索条件完成多个任务，使用时区感知到期比较

评论管理

  • Todoist Comment Create：向任务添加评论，可选附件
  • Todoist Comment Get：检索任务或项目的评论

标签管理

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

项目管理

  • Todoist Project Create：创建具有可选颜色和收藏状态的新项目
  • Todoist Project Get：列出所有项目及其ID和名称

部分管理

  • Todoist Section Create：在项目内创建部分
  • Todoist Section Get：列出项目内的部分

测试与验证

  • Todoist Test Connection：验证API令牌并测试连接性
  • Todoist Test All Features：两种模式 - 基本（只读API测试）和增强（全面的CRUD测试并清理）
  • Todoist Test Performance：基准测试API响应时间，可配置迭代次数

故障排除

常见问题

“未找到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有权读取配置文件

使用示例

项目和部分设置

"显示我所有的项目"
"创建一个新的项目叫'工作任务'"
"在项目12345中创建一个部分叫'正在进行中'"
"显示工作任务项目中的部分"

任务创建与管理

"在项目12345中创建任务'团队会议'"
"添加任务'Review PR'，截止日期为明天，标签['代码审查', '紧急']"
"创建具有截止日期2024-12-25的高优先级任务"
"更新会议任务使其在部分67890中"
"标记代码审查任务为已完成"

# 通过ID识别任务（比名称搜索更可靠）
"获取ID为1234567890的任务"
"更新任务ID 1234567890的优先级为4"
"完成ID为1234567890的任务"
"删除ID为1234567890的任务"

子任务管理

"在任务'团队会议'下创建子任务'准备议程'"
"为'启动项目'创建多个子任务：'设计UI', '编写测试', '部署'"
"将任务'代码审查'转换为'发布v2.0'的子任务"
"提升子任务'修复bug'为主任务"
"显示带有完成跟踪的'启动项目'的任务层次结构"

批量操作

"为项目启动创建多个任务：'设计草图', '编写文档', '设置CI/CD'"
"将所有高优先级任务更新为下周到期"
"完成项目12345中包含'review'的所有任务"
"删除所有过期且优先级为1的任务"

评论管理

"向任务'Review PR'添加评论'This needs urgent attention'"
"向任务67890添加带附件的评论"
"显示任务'团队会议'的所有评论"
"获取项目12345的评论"

标签管理

"显示我所有的标签"
"创建一个名为'紧急'的新标签，颜色为红色"
"更新'工作'标签为蓝色并标记为收藏"
"删除未使用的'旧项目'标签"
"获取所有标签的使用统计信息"

任务发现

"显示我所有的任务"
"列出本周到期的高优先级任务"
"获取项目12345中的任务"

测试与验证

"测试我的Todoist连接"
"对所有Todoist功能运行基本测试" // 默认：只读API测试
"对所有Todoist功能运行增强测试" // 全面的CRUD测试并清理
"基准测试Todoist API性能，10次迭代"
"验证所有MCP工具是否正常工作"

干运行测试

当启用干运行模式（DRYRUN=true）时，使用常规命令 - 它们将自动被模拟：

"创建一个优先级为1的测试任务"
"将所有逾期任务更新为明天到期"
"删除项目12345中已完成的所有任务"
"在任务'项目规划'下创建5个子任务"

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

入门工作流程

第一步

"测试我的Todoist连接"
"显示我所有的Todoist项目"
"创建一个名为'Claude集成测试'的新项目"

基本任务管理

"在我的收件箱中创建任务'尝试MCP集成'"
"添加一个高优先级任务'Review项目设置'，截止日期为明天"
"显示我所有的任务"

高级组织

"在我的工作项目中创建一个部分叫'正在进行中'"
"将设置任务移动到正在进行中部分"
"向我的测试任务添加评论'This is working great!'"

批量操作

"创建多个任务：'计划会议议程', '准备幻灯片', '发送邀请'"
"完成Claude项目中包含'test'的所有任务"
"将所有高优先级任务更新为下周到期"

最佳实践

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

开发

从源码构建

# 克隆仓库
git clone https://github.com/greirson/mcp-todoist.git

# 导航到目录
cd mcp-todoist

# 安装依赖
npm install

# 构建项目
npm run build

开发命令

# 监视更改并重建
npm run watch

# 运行测试
npm run test

# 在监视模式下运行测试
npm run test:watch

# 运行带有覆盖率的测试
npm run test:coverage

# 检查代码
npm run lint

# 修复代码检查问题
npm run lint:fix

# 格式化代码
npm run format

# 检查格式
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 - 评论