使用说明

Todoist MCP 服务器

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

为何选择这个工具？

Todoist是最受欢迎的任务管理平台之一，帮助数百万人组织他们的工作和生活。这款MCP服务器将人工智能辅助任务管理的强大功能融入到您的工作流程中，实现：

自然语言任务创建使用对话语言创建任务
智能组织人工智能可以帮助你将任务组织成项目和部分
智能优先级设定根据上下文自动设置优先级和截止日期
批量操作高效执行多项操作
情境感知管理AI能够理解您的任务背景并提出改进建议

特性/功能

全面集成Todoist功能通过官方API全面访问任务、项目、板块和标签
类型安全的实现用TypeScript编写，包含全面的类型定义
输入验证使用Zod架构对所有API输入进行严格验证
错误处理优雅地处理错误，提供信息丰富的消息
批处理操作支持一次性创建、更新和管理多个项目
MCP集成与Claude、Cursor、Windsurf、Cline及其他MCP主机完全兼容

可用工具

任务管理

在Todoist中创建任务创建一个或多个任务，支持所有参数
- 设置内容、描述、截止日期、优先级
- 分配给项目和部门
- 添加标签和父任务
- 支持持续时间和截止日期字段
获取Todoist任务使用灵活过滤功能检索任务
- 按项目、部分、标签或优先级筛选
- 使用自然语言过滤器（'今天'、'明天'、'已逾期'）
- 分页支持
更新Todoist任务通过ID或名称更新现有任务
- 修改任何任务属性
- 支持批量更新
移动Todoist任务将任务移动到不同的项目、部分或上级任务中
- 更改任务位置（使用此功能代替更新以进行移动）
- 转移到另一个项目、部分，或将其设为子任务
- 支持批量移动
Todoist删除任务按ID或名称删除任务
- 支持批量删除
完成Todoist任务将任务标记为已完成
- 支持批量完成

项目管理

获取Todoist项目列表检索所有项目，可选层次结构
- 为每个项目包含相应部分
- 按特定项目ID筛选
在Todoist中创建项目创建新项目
- 设置颜色，查看样式（列表/看板）
- 创建具有父级ID的嵌套项目
- 标记为收藏
- 在项目创建过程中可选择性地创建部分
更新Todoist项目更新现有项目
- 修改名称、颜色、收藏状态、查看样式
- 按ID更新或按名称搜索

部门管理

获取Todoist项目板块从一个或多个项目中获取部分
- 支持批量检索
- 按项目ID或名称查找
Todoist 创建项目板块在项目中创建部分
- 设置部分名称和顺序
- 支持批量创建

标签管理

获取Todoist个人标签检索所有个人标签
获取Todoist个人标签通过ID获取特定标签
在Todoist中创建个人标签创建新标签
- 设置颜色和收藏状态
- 定义标签顺序
- 支持批量创建
更新Todoist个人标签更新现有标签
- 修改名称、颜色、顺序、收藏状态
- 按ID更新或按名称搜索
删除Todoist个人标签从您的账户中移除标签

用例

为了提升个人生产力

每日计划人工智能可以通过创建和设定任务优先级来帮助你安排一天的事务
收件箱处理快速将任务想法转化为有条理的项目
回顾与反思人工智能可以分析你的任务模式并提出改进建议

针对知识工作者

会议后续跟进自动从会议记录中创建行动项
项目规划将大型项目分解为可管理的任务和部分
工作负载管理根据优先级和截止日期，在项目间平衡任务分配

为了团队协作

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

安装

使用Smithery（推荐）

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

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

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

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

# For 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令牌

访问 Todoist 设置 > 集成 > 开发者
登录您的Todoist账户
滚动到“API令牌”部分
复制您的API令牌
重要的请不要分享您的API令牌或将其提交到源代码控制系统中

示例工作流

创建任务

{
  "tool": "todoist_create_task",
  "arguments": {
    "content": "Review quarterly goals",
    "description": "Analyze Q4 performance and set Q1 objectives",
    "due_string": "tomorrow at 2pm",
    "priority": 3,
    "labels": ["work", "planning"]
  }
}

获取今日任务

{
  "tool": "todoist_get_tasks",
  "arguments": {
    "filter": "today"
  }
}

创建包含章节的项目

{
  "tool": "todoist_create_project",
  "arguments": {
    "name": "Website Redesign",
    "color": "blue",
    "view_style": "board",
    "sections": ["Design", "Development", "Testing"]
  }
}

批量任务创建

{
  "tool": "todoist_create_task",
  "arguments": {
    "tasks": [
      {
        "content": "Design homepage mockup",
        "due_string": "Monday",
        "priority": 4
      },
      {
        "content": "Set up development environment",
        "due_string": "Tuesday"
      },
      {
        "content": "Create component library",
        "due_string": "Wednesday"
      }
    ]
  }
}

按名称更新任务

{
  "tool": "todoist_update_task",
  "arguments": {
    "task_name": "Review quarterly goals",
    "priority": 4,
    "due_string": "today"
  }
}

将任务移动到不同项目

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

完成多项任务

{
  "tool": "todoist_complete_task",
  "arguments": {
    "tasks": [
      { "task_name": "Morning standup" },
      { "task_name": "Email review" },
      { "task_name": "Code review" }
    ]
  }
}

项目结构

mcp-todoist/
├── src/
│   ├── index.ts          # Main MCP server entry point
│   └── todoist/          # Todoist integration
│       ├── client.ts     # Todoist client implementation
│       └── types.ts      # TypeScript type definitions
├── docs/                 # Documentation
├── package.json          # Project configuration
└── tsconfig.json         # TypeScript configuration

对于开发者

开发命令

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

部署选项

HTTP 流（推荐）

pnpm run build:http
pnpm run start:http

传统标准I/O库（旧版）

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是一家精品咨询公司，其使命是开发和拓展用户界面如何利用人工智能技术的方法。我们致力于在人工智能与用户体验的交汇点上构建宏伟蓝图，公司由Ben Hofferber创立并领导。

我们为希望采用AI工具但又不想成为开发者的团队提供专门的人工智能工作坊。了解更多关于我们的培训和研讨会信息。