Todoist MCP 服务器

这是一个模型上下文协议（MCP）服务器，它连接AI助手与Todoist，实现无缝的任务管理。此服务器使AI助手能够创建、读取、更新和完成任务，管理项目，组织部分，并在您的Todoist账户中处理标签。

为什么选择这个工具？

Todoist是流行的任务管理平台之一，帮助数百万人组织他们的工作和生活。这个MCP服务器将AI辅助任务管理的力量带入您的工作流程，实现以下功能：

• 自然语言任务创建：使用对话语言创建任务
• 智能组织：AI可以帮助您将任务组织到项目和部分中
• 智能优先级设置：根据上下文自动设置优先级和截止日期
• 批量操作：高效执行多个操作
• 上下文感知管理：AI可以理解任务上下文并提出改进建议

功能

• 全面的Todoist集成：通过官方API访问任务、项目、部分和标签
• 类型安全实现：使用TypeScript编写，具有完整的类型定义
• 输入验证：使用Zod模式对所有API输入进行强大的验证
• 错误处理：优雅的错误处理，带有信息性消息
• 批量操作：支持一次创建、更新和管理多个项目
• MCP集成：完全兼容Claude、Cursor、Windsurf、Cline和其他MCP主机

可用工具

任务管理

• todoist_create_task：创建一个或多个任务，支持所有参数

  • 设置内容、描述、截止日期、优先级
  • 分配给项目和部分
  • 添加标签和父任务
  • 支持持续时间和截止日期字段

• todoist_get_tasks：检索任务，支持灵活过滤

  • 按项目、部分、标签或优先级过滤
  • 使用自然语言过滤器（'今天'、'明天'、'逾期'）
  • 支持分页

• todoist_update_task：通过ID或名称更新现有任务

  • 修改任何任务属性
  • 支持批量更新

• todoist_move_task：将任务移动到不同的项目、部分或父任务

  • 更改任务位置（用于移动时使用）
  • 移动到不同的项目、部分或作为子任务

• 支持批量移动

• todoist_delete_task：通过ID或名称删除任务

  • 支持批量删除

• todoist_complete_task：标记任务为已完成

  • 支持批量完成

项目管理

• todoist_get_projects：检索所有项目，可选层次结构

  • 包括每个项目的部分
  • 按特定项目ID过滤

• todoist_create_project：创建新项目

  • 设置颜色、视图样式（列表/看板）
  • 创建嵌套项目，使用parent_id
  • 标记为收藏
  • 在创建项目时可选创建部分

• todoist_update_project：更新现有项目

  • 修改名称、颜色、收藏状态、视图样式
  • 通过ID或名称搜索更新

部分管理

• todoist_get_project_sections：从一个或多个项目获取部分

  • 支持批量检索
  • 通过项目ID或名称查找

• todoist_create_project_section：在项目内创建部分

  • 设置部分名称和顺序
  • 支持批量创建

标签管理

• todoist_get_personal_labels：检索所有个人标签

• todoist_get_personal_label：通过ID获取特定标签

• todoist_create_personal_label：创建新标签

  • 设置颜色和收藏状态
  • 定义标签顺序
  • 支持批量创建

• todoist_update_personal_label：更新现有标签

  • 修改名称、颜色、顺序、收藏状态
  • 通过ID或名称搜索更新

• todoist_delete_personal_label：从您的账户中删除标签

使用场景

个人生产力

• 日常规划：AI可以帮助您通过创建和优先级设置来组织一天
• 收件箱处理：快速将任务想法转化为有组织的项目
• 回顾与反思：AI可以分析您的任务模式并提出改进建议

知识工作者

• 会议跟进：自动从会议记录中创建行动项
• 项目规划：将大型项目分解为可管理的任务和部分
• 工作量管理：基于优先级和截止日期平衡任务

团队协作

• 任务委派：分配任务给团队成员
• 项目组织：跨团队创建一致的项目结构
• 进度跟踪：监控任务完成情况和项目状态

安装

使用Smithery（推荐）

安装Todoist MCP最简单的方法是使用Smithery：

# 对于Claude Desktop
npx -y @smithery/cli install @Hint-Services/mcp-todoist --client claude

# 对于Cursor
npx -y @smithery/cli install @Hint-Services/mcp-todoist --client cursor

# 对于Windsurf
npx -y @smithery/cli install @Hint-Services/mcp-todoist --client windsurf

# 对于Cline
npx -y @smithery/cli install @Hint-Services/mcp-todoist --client cline

手动安装

npm install @hoffination/mcp-todoist

配置

将服务器添加到您的MCP设置文件中，使用以下配置：

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["-y", "@hoffination/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your-todoist-api-token"
      }
    }
  }
}

必需的环境变量

• TODOIST_API_TOKEN：您的Todoist API令牌（在这里获取）

获取您的API令牌

1. 访问Todoist 设置 > 集成 > 开发者
2. 登录您的Todoist账户
3. 滚动到“API令牌”部分
4. 复制您的API令牌
5. 重要：永远不要分享您的API令牌或将其提交到源控制

示例工作流

创建任务

{
  "tool": "todoist_create_task",
  "arguments": {
    "content": "审查季度目标",
    "description": "分析Q4表现并设定Q1目标",
    "due_string": "明天下午2点",
    "priority": 3,
    "labels": ["工作", "计划"]
  }
}

获取今天的任务

{
  "tool": "todoist_get_tasks",
  "arguments": {
    "filter": "今天"
  }
}

创建带有部分的项目

{
  "tool": "todoist_create_project",
  "arguments": {
    "name": "网站重新设计",
    "color": "蓝色",
    "view_style": "看板",
    "sections": ["设计", "开发", "测试"]
  }
}

批量创建任务

{
  "tool": "todoist_create_task",
  "arguments": {
    "tasks": [
      {
        "content": "设计首页草图",
        "due_string": "周一",
        "priority": 4
      },
      {
        "content": "设置开发环境",
        "due_string": "周二"
      },
      {
        "content": "创建组件库",
        "due_string": "周三"
      }
    ]
  }
}

通过名称更新任务

{
  "tool": "todoist_update_task",
  "arguments": {
    "task_name": "审查季度目标",
    "priority": 4,
    "due_string": "今天"
  }
}

将任务移动到不同项目

{
  "tool": "todoist_move_task",
  "arguments": {
    "task_id": "6f624qq0GfvXJR9C",
    "project_id": "6XvWFBgqvg9qPVH2"
  }
}

完成多个任务

{
  "tool": "todoist_complete_task",
  "arguments": {
    "tasks": [
      { "task_name": "早晨站会" },
      { "task_name": "邮件审查" },
      { "task_name": "代码审查" }
    ]
  }
}

项目结构

mcp-todoist/
├── src/
│   ├── index.ts          # 主MCP服务器入口点
│   └── todoist/          # Todoist集成
│       ├── client.ts     # Todoist客户端实现
│       └── types.ts      # TypeScript类型定义
├── docs/                 # 文档
├── package.json          # 项目配置
└── tsconfig.json         # TypeScript配置

开发者指南

开发命令

• pnpm install - 安装依赖
• pnpm run build - 构建项目以供HTTP流传输（默认）
• pnpm run dev - 在开发模式下运行，支持热重载
• pnpm run inspector - 启动MCP检查器进行测试（stdio模式）
• pnpm run test - 运行测试
• pnpm run lint:fix - 修复lint问题
• pnpm run format:fix - 格式化代码

部署选项

HTTP流传输（推荐）

pnpm run build:http
pnpm run start:http

传统stdio（遗留）

pnpm run build:stdio
pnpm run start:stdio

HTTP流接口提供更好的性能和简化部署，无需Docker，同时保持与传统stdio接口的完全向后兼容性。

API参考

该服务器实现了15个Todoist工具，分为四个类别：

任务工具

• todoist_create_task
• todoist_get_tasks
• todoist_update_task
• todoist_move_task
• todoist_delete_task
• todoist_complete_task

项目工具

• todoist_get_projects
• todoist_create_project
• todoist_update_project
• todoist_get_project_sections
• todoist_create_project_section

标签工具

• todoist_get_personal_labels
• todoist_get_personal_label
• todoist_create_personal_label
• todoist_update_personal_label
• todoist_delete_personal_label

详细的API文档，请参阅Todoist API v1文档。

隐私与安全

• 您的API令牌仅用于与Todoist官方API进行身份验证
• 该MCP服务器不存储或缓存任何数据
• 所有通信都是直接在您的客户端和Todoist服务器之间进行
• 遵循Todoist的隐私政策和服务条款

故障排除

API令牌问题

• 确保您的API令牌有效且未过期
• 检查是否使用了正确的环境变量名称：TODOIST_API_TOKEN
• 验证您的Todoist账户已启用API访问

任务未出现

• 确认您查询的是正确的项目或使用了正确的过滤器
• 检查任务是否已被完成或删除
• 验证项目和部分ID是否正确

连接问题

• 检查您的互联网连接
• 验证Todoist服务是否正常运行
• 确保您使用的是最新版本的MCP服务器

常见错误

• "任务未找到"：任务名称搜索未能找到匹配的任务
• "项目未找到"：无效的项目ID或名称
• "无效颜色"：使用有效的Todoist颜色名称（例如，“蓝色”，“红色”，“绿色”）

更多信息

进一步的信息，请参阅：

• Todoist API v1文档：官方API文档
• 模型上下文协议文档：MCP架构和设计原则
• Smithery - MCP服务器注册表：发布MCP服务器的指南
• MCP TypeScript SDK文档：全面的TypeScript SDK文档

关于Hint Services

“未来已经到来，只是分布得不均匀”

—— William Gibson，作家

Hint Services是一家精品咨询公司，致力于开发和扩展用户界面如何利用人工智能技术。我们在AI和用户体验交叉点上构想雄心壮志，由Ben Hofferber创立并领导。

我们为设计团队提供专门的AI研讨会，这些团队希望拥抱AI工具而不必成为开发者。了解更多关于我们的培训和研讨会。