todoist-automation
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTodoist Automation via Rube MCP
通过Rube MCP实现Todoist自动化
Automate Todoist operations including task creation and management, project organization, section management, filtering, and bulk task workflows through Composio's Todoist toolkit.
Toolkit docs: composio.dev/toolkits/todoist
通过Composio的Todoist工具包,实现Todoist操作的自动化,包括任务创建与管理、项目组织、分区管理、筛选以及批量任务工作流。
Prerequisites
前提条件
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
- Active Todoist connection via with toolkit
RUBE_MANAGE_CONNECTIONStodoist - Always call first to get current tool schemas
RUBE_SEARCH_TOOLS
- 已连接Rube MCP(需提供RUBE_SEARCH_TOOLS)
- 通过并使用
RUBE_MANAGE_CONNECTIONS工具包建立有效的Todoist连接todoist - 请始终先调用以获取最新的工具架构
RUBE_SEARCH_TOOLS
Setup
设置步骤
Get Rube MCP: Add as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
https://rube.app/mcp- Verify Rube MCP is available by confirming responds
RUBE_SEARCH_TOOLS - Call with toolkit
RUBE_MANAGE_CONNECTIONStodoist - If connection is not ACTIVE, follow the returned auth link to complete Todoist OAuth
- Confirm connection status shows ACTIVE before running any workflows
获取Rube MCP:在客户端配置中添加作为MCP服务器。无需API密钥,只需添加该端点即可使用。
https://rube.app/mcp- 通过确认能响应,验证Rube MCP是否可用
RUBE_SEARCH_TOOLS - 调用并指定工具包为
RUBE_MANAGE_CONNECTIONStodoist - 如果连接未处于ACTIVE状态,请跟随返回的授权链接完成Todoist OAuth认证
- 在运行任何工作流之前,确认连接状态显示为ACTIVE
Core Workflows
核心工作流
1. Create and Manage Tasks
1. 创建与管理任务
When to use: User wants to create, update, complete, reopen, or delete tasks
Tool sequence:
- - List projects to find the target project ID [Prerequisite]
TODOIST_GET_ALL_PROJECTS - - List sections within a project for task placement [Optional]
TODOIST_GET_ALL_SECTIONS - - Create a single task with content, due date, priority, labels [Required]
TODOIST_CREATE_TASK - - Create multiple tasks in one request [Alternative]
TODOIST_BULK_CREATE_TASKS - - Modify task properties (content, due date, priority, labels) [Optional]
TODOIST_UPDATE_TASK - - Mark a task as completed [Optional]
TODOIST_CLOSE_TASK - - Restore a previously completed task [Optional]
TODOIST_REOPEN_TASK - - Permanently remove a task [Optional]
TODOIST_DELETE_TASK
Key parameters for CREATE_TASK:
- : Task title (supports markdown and hyperlinks)
content - : Additional notes (do NOT put due dates here)
description - : Alphanumeric project ID; omit to add to Inbox
project_id - : Alphanumeric section ID for placement within a project
section_id - : Task ID for creating subtasks
parent_id - : 1 (normal) to 4 (urgent) -- note: Todoist UI shows p1=urgent, API p4=urgent
priority - : Natural language date like
due_string,"tomorrow at 3pm""every Friday at 9am" - : Specific date
due_dateformatYYYY-MM-DD - : Specific date+time in RFC3339
due_datetimeYYYY-MM-DDTHH:mm:ssZ - : Array of label name strings
labels - +
duration: Task duration (e.g.,duration_unit+30)"minute"
Pitfalls:
- Only one field can be used at a time (except
due_*which can accompany any)due_lang - Do NOT embed due dates in or
content-- usedescriptionfielddue_string - Do NOT embed duration phrases like "for 30 minutes" in -- use
due_string+durationduration_unit - in API: 1=normal, 4=urgent (opposite of Todoist UI display where p1=urgent)
priority - Task IDs can be numeric or alphanumeric; use the format returned by the API
- marks complete;
CLOSE_TASKpermanently removes -- they are different operationsDELETE_TASK
适用场景:用户需要创建、更新、完成、重新打开或删除任务
工具执行顺序:
- - 列出所有项目以找到目标项目ID [必要前提]
TODOIST_GET_ALL_PROJECTS - - 列出项目内的分区,用于任务定位 [可选]
TODOIST_GET_ALL_SECTIONS - - 创建单个任务,包含内容、截止日期、优先级、标签 [必要]
TODOIST_CREATE_TASK - - 一次请求创建多个任务 [替代方案]
TODOIST_BULK_CREATE_TASKS - - 修改任务属性(内容、截止日期、优先级、标签) [可选]
TODOIST_UPDATE_TASK - - 将任务标记为已完成 [可选]
TODOIST_CLOSE_TASK - - 恢复已完成的任务 [可选]
TODOIST_REOPEN_TASK - - 永久删除任务 [可选]
TODOIST_DELETE_TASK
CREATE_TASK关键参数:
- : 任务标题(支持markdown和超链接)
content - : 附加说明(请勿在此处填写截止日期)
description - : 字母数字格式的项目ID;留空则添加到收件箱
project_id - : 字母数字格式的分区ID,用于指定任务在项目中的位置
section_id - : 父任务ID,用于创建子任务
parent_id - : 1(普通)到4(紧急)——注意:Todoist界面中p1代表紧急,而API中p4代表紧急
priority - : 自然语言格式的日期,例如
due_string、"tomorrow at 3pm""every Friday at 9am" - : 特定日期,格式为
due_dateYYYY-MM-DD - : 特定日期和时间,格式为RFC3339标准的
due_datetimeYYYY-MM-DDTHH:mm:ssZ - : 标签名称字符串数组
labels - +
duration: 任务时长(例如duration_unit+30)"minute"
注意事项:
- 同一时间只能使用一个字段(
due_*可与任意due_lang字段搭配使用)due_* - 请勿在或
content中嵌入截止日期——请使用description字段due_string - 请勿在中嵌入时长描述如"for 30 minutes"——请使用
due_string+durationduration_unit - API中的优先级:1=普通,4=紧急(与Todoist界面显示相反,界面中p1=紧急)
- 任务ID可以是数字或字母数字格式;请使用API返回的格式
- 是标记完成;
CLOSE_TASK是永久删除——二者是不同操作DELETE_TASK
2. Manage Projects
2. 项目管理
When to use: User wants to list, create, update, or inspect projects
Tool sequence:
- - List all projects with metadata [Required]
TODOIST_GET_ALL_PROJECTS - - Get details for a specific project by ID [Optional]
TODOIST_GET_PROJECT - - Create a new project with name, color, view style [Optional]
TODOIST_CREATE_PROJECT - - Modify project properties [Optional]
TODOIST_UPDATE_PROJECT
Key parameters:
- : Project name (required for creation)
name - : Todoist palette color (e.g.,
color,"blue","red","green")"charcoal" - :
view_styleor"list"layout"board" - : Parent project ID for creating sub-projects
parent_id - /
is_favorite: Boolean to mark as favoritefavorite - : Required for update and get operations
project_id
Pitfalls:
- Projects with similar names can lead to selecting the wrong project_id; always verify
- uses
CREATE_PROJECTwhilefavoriteusesUPDATE_PROJECT-- different field namesis_favorite - Use the project returned by API, not the
id, for downstream operationsv2_id - Alphanumeric/URL-style project IDs may cause HTTP 400 in some tools; use numeric ID if available
适用场景:用户需要列出、创建、更新或查看项目
工具执行顺序:
- - 列出所有项目及其元数据 [必要]
TODOIST_GET_ALL_PROJECTS - - 通过ID获取特定项目的详细信息 [可选]
TODOIST_GET_PROJECT - - 创建新项目,包含名称、颜色、视图样式 [可选]
TODOIST_CREATE_PROJECT - - 修改项目属性 [可选]
TODOIST_UPDATE_PROJECT
关键参数:
- : 项目名称(创建时必填)
name - : Todoist调色板颜色(例如
color、"blue"、"red"、"green")"charcoal" - :
view_style(列表)或"list"(看板)布局"board" - : 父项目ID,用于创建子项目
parent_id - /
is_favorite: 布尔值,标记为收藏favorite - : 更新和查询操作时必填
project_id
注意事项:
- 名称相似的项目可能导致选择错误的project_id;请始终验证
- 使用
CREATE_PROJECT字段,而favorite使用UPDATE_PROJECT字段——字段名称不同is_favorite - 后续操作请使用API返回的项目,而非
idv2_id - 部分工具可能不支持字母数字/URL格式的项目ID,若出现HTTP 400错误,请尝试使用数字ID
3. Manage Sections
3. 分区管理
When to use: User wants to organize tasks within projects using sections
Tool sequence:
- - Find the target project ID [Prerequisite]
TODOIST_GET_ALL_PROJECTS - - List existing sections to avoid duplicates [Prerequisite]
TODOIST_GET_ALL_SECTIONS - - Create a new section in a project [Required]
TODOIST_CREATE_SECTION - - Rename an existing section [Optional]
TODOIST_UPDATE_SECTION - - Permanently remove a section [Optional]
TODOIST_DELETE_SECTION
Key parameters:
- : Required -- the project to create the section in
project_id - : Section name (required for creation)
name - : Integer position within the project (lower values appear first)
order - : Required for update and delete operations
section_id
Pitfalls:
- requires
CREATE_SECTIONandproject_id-- omitting project_id causes a 400 errorname - HTTP 400 "project_id is invalid" can occur if alphanumeric ID is used; prefer numeric ID
- Deleting a section may move or regroup its tasks in non-obvious ways
- Response may include both and
id; store and reuse the correct identifier consistentlyv2_id - Always check existing sections first to avoid creating duplicates
适用场景:用户需要使用分区来组织项目内的任务
工具执行顺序:
- - 找到目标项目ID [必要前提]
TODOIST_GET_ALL_PROJECTS - - 列出已有分区以避免重复创建 [必要前提]
TODOIST_GET_ALL_SECTIONS - - 在项目中创建新分区 [必要]
TODOIST_CREATE_SECTION - - 重命名已有分区 [可选]
TODOIST_UPDATE_SECTION - - 永久删除分区 [可选]
TODOIST_DELETE_SECTION
关键参数:
- : 必填——创建分区所属的项目
project_id - : 分区名称(创建时必填)
name - : 整数,代表分区在项目中的位置(数值越小越靠前)
order - : 更新和删除操作时必填
section_id
注意事项:
- 需要
CREATE_SECTION和project_id——缺少project_id会导致400错误name - 若使用字母数字ID,可能出现HTTP 400错误“project_id is invalid”;建议使用数字ID
- 删除分区可能会以非预期的方式移动或重组其下的任务
- 响应可能同时包含和
id;请始终存储并使用正确的标识符v2_id - 请始终先检查已有分区,避免重复创建
4. Search and Filter Tasks
4. 任务搜索与筛选
When to use: User wants to find tasks by criteria, view today's tasks, or get completed task history
Tool sequence:
- - Fetch incomplete tasks with optional filter query [Required]
TODOIST_GET_ALL_TASKS - - Get full details of a specific task by ID [Optional]
TODOIST_GET_TASK - - Retrieve completed tasks within a date range [Optional]
TODOIST_GET_COMPLETED_TASKS_BY_COMPLETION_DATE - - List user's custom saved filters [Optional]
TODOIST_LIST_FILTERS
Key parameters for GET_ALL_TASKS:
- : Todoist filter syntax string
filter- Keywords: ,
today,tomorrow,overdue,no date,recurringsubtask - Priority: (urgent),
p1,p2,p3(normal)p4 - Projects: (must exist in account)
#ProjectName - Labels: (must exist in account)
@LabelName - Date ranges: ,
7 days,-7 days,due before: YYYY-MM-DDdue after: YYYY-MM-DD - Search: for content text search
search: keyword - Operators: (AND),
&(OR),|(NOT)!
- Keywords:
- : List of specific task IDs to retrieve
ids
Key parameters for GET_COMPLETED_TASKS_BY_COMPLETION_DATE:
- : Start date in RFC3339 format (e.g.,
since)2024-01-01T00:00:00Z - : End date in RFC3339 format
until - ,
project_id,section_id: Optional filtersparent_id - : Pagination cursor from previous response
cursor - : Max results per page (default 50)
limit
Pitfalls:
- returns ONLY incomplete tasks; use
GET_ALL_TASKSfor completed onesGET_COMPLETED_TASKS_BY_COMPLETION_DATE - Filter terms must reference ACTUAL EXISTING entities; arbitrary text causes HTTP 400 errors
- Do NOT use ,
completed, or!completedin GET_ALL_TASKS filter -- causes 400 errorcompleted after - limits date range to approximately 3 months between
GET_COMPLETED_TASKS_BY_COMPLETION_DATEandsinceuntil - Search uses syntax within the filter, not a separate parameter
search: keyword
适用场景:用户需要按条件查找任务、查看今日任务或获取已完成任务历史
工具执行顺序:
- - 获取未完成任务,可附加筛选条件 [必要]
TODOIST_GET_ALL_TASKS - - 通过ID获取特定任务的完整信息 [可选]
TODOIST_GET_TASK - - 获取指定日期范围内的已完成任务 [可选]
TODOIST_GET_COMPLETED_TASKS_BY_COMPLETION_DATE - - 列出用户自定义的保存筛选器 [可选]
TODOIST_LIST_FILTERS
GET_ALL_TASKS关键参数:
- : Todoist筛选语法字符串
filter- 关键词: 、
today、tomorrow、overdue、no date、recurringsubtask - 优先级: (紧急)、
p1、p2、p3(普通)p4 - 项目: (必须是账户中已存在的项目)
#ProjectName - 标签: (必须是账户中已存在的标签)
@LabelName - 日期范围: 、
7 days、-7 days、due before: YYYY-MM-DDdue after: YYYY-MM-DD - 搜索: 用于内容文本搜索
search: keyword - 运算符: (与)、
&(或)、|(非)!
- 关键词:
- : 要获取的特定任务ID列表
ids
GET_COMPLETED_TASKS_BY_COMPLETION_DATE关键参数:
- : 开始日期,格式为RFC3339(例如
since)2024-01-01T00:00:00Z - : 结束日期,格式为RFC3339
until - ,
project_id,section_id: 可选筛选条件parent_id - : 来自上一次响应的分页游标
cursor - : 每页最大结果数(默认50)
limit
注意事项:
- 仅返回未完成任务;请使用
TODOIST_GET_ALL_TASKS获取已完成任务TODOIST_GET_COMPLETED_TASKS_BY_COMPLETION_DATE - 筛选条件必须引用账户中实际存在的实体;任意文本会导致HTTP 400错误
- 请勿在GET_ALL_TASKS的筛选条件中使用、
completed或!completed——会导致400错误completed after - 的日期范围限制为
TODOIST_GET_COMPLETED_TASKS_BY_COMPLETION_DATE和since之间约3个月until - 文本搜索需在筛选条件中使用语法,而非单独参数
search: keyword
5. Bulk Task Creation
5. 批量任务创建
When to use: User wants to scaffold a project with multiple tasks at once
Tool sequence:
- - Find target project ID [Prerequisite]
TODOIST_GET_ALL_PROJECTS - - Find section IDs for task placement [Optional]
TODOIST_GET_ALL_SECTIONS - - Create multiple tasks in a single request [Required]
TODOIST_BULK_CREATE_TASKS
Key parameters:
- : Array of task objects, each requiring at minimum
taskscontent - Each task object supports: ,
content,description,project_id,section_id,parent_id,priority,labels(object withdue,string, ordate),datetime,durationorder
Pitfalls:
- Each task in the array must have at least the field
content - The field in bulk create is an object with nested fields (
due,string,date,datetime) -- different structure from CREATE_TASK's flat fieldslang - All tasks can target different projects/sections within the same batch
适用场景:用户需要一次性为项目创建多个任务
工具执行顺序:
- - 找到目标项目ID [必要前提]
TODOIST_GET_ALL_PROJECTS - - 找到分区ID用于任务定位 [可选]
TODOIST_GET_ALL_SECTIONS - - 一次请求创建多个任务 [必要]
TODOIST_BULK_CREATE_TASKS
关键参数:
- : 任务对象数组,每个任务至少需要
tasks字段content - 每个任务对象支持:、
content、description、project_id、section_id、parent_id、priority、labels(包含due、string或date的对象)、datetime、durationorder
注意事项:
- 数组中的每个任务必须至少包含字段
content - 批量创建中的字段是一个包含嵌套字段(
due、string、date、datetime)的对象——与CREATE_TASK的扁平字段结构不同lang - 同一批次中的任务可以指向不同的项目/分区
Common Patterns
通用模式
ID Resolution
ID解析
Always resolve human-readable names to IDs before operations:
- Project name -> Project ID: , match by
TODOIST_GET_ALL_PROJECTSfieldname - Section name -> Section ID: with
TODOIST_GET_ALL_SECTIONSproject_id - Task content -> Task ID: with
TODOIST_GET_ALL_TASKSorfiltersearch: keyword
在执行操作前,请始终将人类可读的名称解析为ID:
- 项目名称 -> 项目ID: 使用,匹配
TODOIST_GET_ALL_PROJECTS字段name - 分区名称 -> 分区ID: 使用并传入
TODOIST_GET_ALL_SECTIONSproject_id - 任务内容 -> 任务ID: 使用并传入
TODOIST_GET_ALL_TASKS或filtersearch: keyword
Pagination
分页处理
- : Returns all matching incomplete tasks (no pagination needed)
TODOIST_GET_ALL_TASKS - : Uses cursor-based pagination; follow
TODOIST_GET_COMPLETED_TASKS_BY_COMPLETION_DATEfrom response until no more resultscursor - and
TODOIST_GET_ALL_PROJECTS: Return all results (no pagination)TODOIST_GET_ALL_SECTIONS
- : 返回所有匹配的未完成任务(无需分页)
TODOIST_GET_ALL_TASKS - : 使用基于游标的分页;请跟随响应中的
TODOIST_GET_COMPLETED_TASKS_BY_COMPLETION_DATE直到没有更多结果cursor - 和
TODOIST_GET_ALL_PROJECTS: 返回所有结果(无需分页)TODOIST_GET_ALL_SECTIONS
Due Date Handling
截止日期处理
- Natural language: Use (e.g.,
due_string,"tomorrow at 3pm")"every Monday" - Specific date: Use in
due_dateformatYYYY-MM-DD - Specific datetime: Use in RFC3339 format (
due_datetime)YYYY-MM-DDTHH:mm:ssZ - Only use ONE due field at a time (except which can accompany any)
due_lang - Recurring tasks: Use natural language in (e.g.,
due_string)"every Friday at 9am"
- 自然语言:使用(例如
due_string、"tomorrow at 3pm")"every Monday" - 特定日期:使用,格式为
due_dateYYYY-MM-DD - 特定日期时间:使用,格式为RFC3339标准的
due_datetimeYYYY-MM-DDTHH:mm:ssZ - 同一时间只能使用一个截止日期字段(可与任意截止日期字段搭配使用)
due_lang - 重复任务:在中使用自然语言(例如
due_string)"every Friday at 9am"
Known Pitfalls
已知注意事项
ID Formats
ID格式
- Task IDs can be numeric () or alphanumeric (
"2995104339")"6X4Vw2Hfmg73Q2XR" - Project IDs similarly vary; prefer the format returned by the API
- Some tools accept only numeric IDs; if 400 error occurs, try fetching the numeric via GET_PROJECT
id - Response objects may contain both and
id; usev2_idfor API operationsid
- 任务ID可以是数字()或字母数字(
"2995104339")格式"6X4Vw2Hfmg73Q2XR" - 项目ID格式类似;请优先使用API返回的格式
- 部分工具仅支持数字ID;若出现400错误,请尝试通过GET_PROJECT获取数字
id - 响应对象可能同时包含和
id;请使用v2_id进行API操作id
Priority Inversion
优先级反转
- API priority: 1 = normal, 4 = urgent
- Todoist UI display: p1 = urgent, p4 = normal
- This is inverted; always clarify with the user which convention they mean
- API中的优先级:1 = 普通,4 = 紧急
- Todoist界面显示:p1 = 紧急,p4 = 普通
- 二者是相反的;请始终向用户确认他们所指的是哪种约定
Filter Syntax
筛选语法
- Filter terms must reference real entities in the user's account
- or
#NonExistentProjectwill cause HTTP 400@NonExistentLabel - Use for text search, not bare keywords
search: keyword - Combine with (AND),
&(OR),|(NOT)! - filters do NOT work on GET_ALL_TASKS endpoint
completed
- 筛选条件必须引用用户账户中的真实实体
- 或
#NonExistentProject会导致HTTP 400错误@NonExistentLabel - 文本搜索请使用,而非直接使用关键词
search: keyword - 使用(与)、
&(或)、|(非)进行组合! - 筛选条件不适用于GET_ALL_TASKS端点
completed
Rate Limits
速率限制
- Todoist API has rate limits; batch operations should use where possible
BULK_CREATE_TASKS - Space out rapid sequential requests to avoid throttling
- Todoist API有速率限制;批量操作请尽可能使用
BULK_CREATE_TASKS - 请间隔快速连续的请求,避免被限流
Quick Reference
快速参考
| Task | Tool Slug | Key Params |
|---|---|---|
| List all projects | | (none) |
| Get project | | |
| Create project | | |
| Update project | | |
| List sections | | |
| Create section | | |
| Update section | | |
| Delete section | | |
| Get all tasks | | |
| Get task | | |
| Create task | | |
| Bulk create tasks | | |
| Update task | | |
| Complete task | | |
| Reopen task | | |
| Delete task | | |
| Completed tasks | | |
| List filters | | |
Powered by Composio
| 任务 | 工具标识 | 关键参数 |
|---|---|---|
| 列出所有项目 | | 无 |
| 获取项目详情 | | |
| 创建项目 | | |
| 更新项目 | | |
| 列出分区 | | |
| 创建分区 | | |
| 更新分区 | | |
| 删除分区 | | |
| 获取所有任务 | | |
| 获取任务详情 | | |
| 创建任务 | | |
| 批量创建任务 | | |
| 更新任务 | | |
| 标记任务完成 | | |
| 重新打开任务 | | |
| 删除任务 | | |
| 获取已完成任务 | | |
| 列出筛选器 | | |
由Composio提供支持