Todoist Automation

1---
2name: todoist-automation
3description: "Automate Todoist task management, projects, sections, filtering, and bulk operations via Rube MCP (Composio). Always search tools first for current schemas."
4requires:
5  mcp: [rube]
6---
7 
8# Todoist Automation via Rube MCP
9 
10Automate Todoist operations including task creation and management, project organization, section management, filtering, and bulk task workflows through Composio's Todoist toolkit.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active Todoist connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `todoist`
16- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
17 
18## Setup
19 
20**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
21 
22 
231. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
242. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `todoist`
253. If connection is not ACTIVE, follow the returned auth link to complete Todoist OAuth
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. Create and Manage Tasks
31 
32**When to use**: User wants to create, update, complete, reopen, or delete tasks
33 
34**Tool sequence**:
351. `TODOIST_GET_ALL_PROJECTS` - List projects to find the target project ID [Prerequisite]
362. `TODOIST_GET_ALL_SECTIONS` - List sections within a project for task placement [Optional]
373. `TODOIST_CREATE_TASK` - Create a single task with content, due date, priority, labels [Required]
384. `TODOIST_BULK_CREATE_TASKS` - Create multiple tasks in one request [Alternative]
395. `TODOIST_UPDATE_TASK` - Modify task properties (content, due date, priority, labels) [Optional]
406. `TODOIST_CLOSE_TASK` - Mark a task as completed [Optional]
417. `TODOIST_REOPEN_TASK` - Restore a previously completed task [Optional]
428. `TODOIST_DELETE_TASK` - Permanently remove a task [Optional]
43 
44**Key parameters for CREATE_TASK**:
45- `content`: Task title (supports markdown and hyperlinks)
46- `description`: Additional notes (do NOT put due dates here)
47- `project_id`: Alphanumeric project ID; omit to add to Inbox
48- `section_id`: Alphanumeric section ID for placement within a project
49- `parent_id`: Task ID for creating subtasks
50- `priority`: 1 (normal) to 4 (urgent) -- note: Todoist UI shows p1=urgent, API p4=urgent
51- `due_string`: Natural language date like `"tomorrow at 3pm"`, `"every Friday at 9am"`
52- `due_date`: Specific date `YYYY-MM-DD` format
53- `due_datetime`: Specific date+time in RFC3339 `YYYY-MM-DDTHH:mm:ssZ`
54- `labels`: Array of label name strings
55- `duration` + `duration_unit`: Task duration (e.g., `30` + `"minute"`)
56 
57**Pitfalls**:
58- Only one `due_*` field can be used at a time (except `due_lang` which can accompany any)
59- Do NOT embed due dates in `content` or `description` -- use `due_string` field
60- Do NOT embed duration phrases like "for 30 minutes" in `due_string` -- use `duration` + `duration_unit`
61- `priority` in API: 1=normal, 4=urgent (opposite of Todoist UI display where p1=urgent)
62- Task IDs can be numeric or alphanumeric; use the format returned by the API
63- `CLOSE_TASK` marks complete; `DELETE_TASK` permanently removes -- they are different operations
64 
65### 2. Manage Projects
66 
67**When to use**: User wants to list, create, update, or inspect projects
68 
69**Tool sequence**:
701. `TODOIST_GET_ALL_PROJECTS` - List all projects with metadata [Required]
712. `TODOIST_GET_PROJECT` - Get details for a specific project by ID [Optional]
723. `TODOIST_CREATE_PROJECT` - Create a new project with name, color, view style [Optional]
734. `TODOIST_UPDATE_PROJECT` - Modify project properties [Optional]
74 
75**Key parameters**:
76- `name`: Project name (required for creation)
77- `color`: Todoist palette color (e.g., `"blue"`, `"red"`, `"green"`, `"charcoal"`)
78- `view_style`: `"list"` or `"board"` layout
79- `parent_id`: Parent project ID for creating sub-projects
80- `is_favorite` / `favorite`: Boolean to mark as favorite
81- `project_id`: Required for update and get operations
82 
83**Pitfalls**:
84- Projects with similar names can lead to selecting the wrong project_id; always verify
85- `CREATE_PROJECT` uses `favorite` while `UPDATE_PROJECT` uses `is_favorite` -- different field names
86- Use the project `id` returned by API, not the `v2_id`, for downstream operations
87- Alphanumeric/URL-style project IDs may cause HTTP 400 in some tools; use numeric ID if available
88 
89### 3. Manage Sections
90 
91**When to use**: User wants to organize tasks within projects using sections
92 
93**Tool sequence**:
941. `TODOIST_GET_ALL_PROJECTS` - Find the target project ID [Prerequisite]
952. `TODOIST_GET_ALL_SECTIONS` - List existing sections to avoid duplicates [Prerequisite]
963. `TODOIST_CREATE_SECTION` - Create a new section in a project [Required]
974. `TODOIST_UPDATE_SECTION` - Rename an existing section [Optional]
985. `TODOIST_DELETE_SECTION` - Permanently remove a section [Optional]
99 
100**Key parameters**:
101- `project_id`: Required -- the project to create the section in
102- `name`: Section name (required for creation)
103- `order`: Integer position within the project (lower values appear first)
104- `section_id`: Required for update and delete operations
105 
106**Pitfalls**:
107- `CREATE_SECTION` requires `project_id` and `name` -- omitting project_id causes a 400 error
108- HTTP 400 "project_id is invalid" can occur if alphanumeric ID is used; prefer numeric ID
109- Deleting a section may move or regroup its tasks in non-obvious ways
110- Response may include both `id` and `v2_id`; store and reuse the correct identifier consistently
111- Always check existing sections first to avoid creating duplicates
112 
113### 4. Search and Filter Tasks
114 
115**When to use**: User wants to find tasks by criteria, view today's tasks, or get completed task history
116 
117**Tool sequence**:
1181. `TODOIST_GET_ALL_TASKS` - Fetch incomplete tasks with optional filter query [Required]
1192. `TODOIST_GET_TASK` - Get full details of a specific task by ID [Optional]
1203. `TODOIST_GET_COMPLETED_TASKS_BY_COMPLETION_DATE` - Retrieve completed tasks within a date range [Optional]
1214. `TODOIST_LIST_FILTERS` - List user's custom saved filters [Optional]
122 
123**Key parameters for GET_ALL_TASKS**:
124- `filter`: Todoist filter syntax string
125  - Keywords: `today`, `tomorrow`, `overdue`, `no date`, `recurring`, `subtask`
126  - Priority: `p1` (urgent), `p2`, `p3`, `p4` (normal)
127  - Projects: `#ProjectName` (must exist in account)
128  - Labels: `@LabelName` (must exist in account)
129  - Date ranges: `7 days`, `-7 days`, `due before: YYYY-MM-DD`, `due after: YYYY-MM-DD`
130  - Search: `search: keyword` for content text search
131  - Operators: `&` (AND), `|` (OR), `!` (NOT)
132- `ids`: List of specific task IDs to retrieve
133 
134**Key parameters for GET_COMPLETED_TASKS_BY_COMPLETION_DATE**:
135- `since`: Start date in RFC3339 format (e.g., `2024-01-01T00:00:00Z`)
136- `until`: End date in RFC3339 format
137- `project_id`, `section_id`, `parent_id`: Optional filters
138- `cursor`: Pagination cursor from previous response
139- `limit`: Max results per page (default 50)
140 
141**Pitfalls**:
142- `GET_ALL_TASKS` returns ONLY incomplete tasks; use `GET_COMPLETED_TASKS_BY_COMPLETION_DATE` for completed ones
143- Filter terms must reference ACTUAL EXISTING entities; arbitrary text causes HTTP 400 errors
144- Do NOT use `completed`, `!completed`, or `completed after` in GET_ALL_TASKS filter -- causes 400 error
145- `GET_COMPLETED_TASKS_BY_COMPLETION_DATE` limits date range to approximately 3 months between `since` and `until`
146- Search uses `search: keyword` syntax within the filter, not a separate parameter
147 
148### 5. Bulk Task Creation
149 
150**When to use**: User wants to scaffold a project with multiple tasks at once
151 
152**Tool sequence**:
1531. `TODOIST_GET_ALL_PROJECTS` - Find target project ID [Prerequisite]
1542. `TODOIST_GET_ALL_SECTIONS` - Find section IDs for task placement [Optional]
1553. `TODOIST_BULK_CREATE_TASKS` - Create multiple tasks in a single request [Required]
156 
157**Key parameters**:
158- `tasks`: Array of task objects, each requiring at minimum `content`
159- Each task object supports: `content`, `description`, `project_id`, `section_id`, `parent_id`, `priority`, `labels`, `due` (object with `string`, `date`, or `datetime`), `duration`, `order`
160 
161**Pitfalls**:
162- Each task in the array must have at least the `content` field
163- The `due` field in bulk create is an object with nested fields (`string`, `date`, `datetime`, `lang`) -- different structure from CREATE_TASK's flat fields
164- All tasks can target different projects/sections within the same batch
165 
166## Common Patterns
167 
168### ID Resolution
169Always resolve human-readable names to IDs before operations:
170- **Project name -> Project ID**: `TODOIST_GET_ALL_PROJECTS`, match by `name` field
171- **Section name -> Section ID**: `TODOIST_GET_ALL_SECTIONS` with `project_id`
172- **Task content -> Task ID**: `TODOIST_GET_ALL_TASKS` with `filter` or `search: keyword`
173 
174### Pagination
175- `TODOIST_GET_ALL_TASKS`: Returns all matching incomplete tasks (no pagination needed)
176- `TODOIST_GET_COMPLETED_TASKS_BY_COMPLETION_DATE`: Uses cursor-based pagination; follow `cursor` from response until no more results
177- `TODOIST_GET_ALL_PROJECTS` and `TODOIST_GET_ALL_SECTIONS`: Return all results (no pagination)
178 
179### Due Date Handling
180- Natural language: Use `due_string` (e.g., `"tomorrow at 3pm"`, `"every Monday"`)
181- Specific date: Use `due_date` in `YYYY-MM-DD` format
182- Specific datetime: Use `due_datetime` in RFC3339 format (`YYYY-MM-DDTHH:mm:ssZ`)
183- Only use ONE due field at a time (except `due_lang` which can accompany any)
184- Recurring tasks: Use natural language in `due_string` (e.g., `"every Friday at 9am"`)
185 
186## Known Pitfalls
187 
188### ID Formats
189- Task IDs can be numeric (`"2995104339"`) or alphanumeric (`"6X4Vw2Hfmg73Q2XR"`)
190- Project IDs similarly vary; prefer the format returned by the API
191- Some tools accept only numeric IDs; if 400 error occurs, try fetching the numeric `id` via GET_PROJECT
192- Response objects may contain both `id` and `v2_id`; use `id` for API operations
193 
194### Priority Inversion
195- API priority: 1 = normal, 4 = urgent
196- Todoist UI display: p1 = urgent, p4 = normal
197- This is inverted; always clarify with the user which convention they mean
198 
199### Filter Syntax
200- Filter terms must reference real entities in the user's account
201- `#NonExistentProject` or `@NonExistentLabel` will cause HTTP 400
202- Use `search: keyword` for text search, not bare keywords
203- Combine with `&` (AND), `|` (OR), `!` (NOT)
204- `completed` filters do NOT work on GET_ALL_TASKS endpoint
205 
206### Rate Limits
207- Todoist API has rate limits; batch operations should use `BULK_CREATE_TASKS` where possible
208- Space out rapid sequential requests to avoid throttling
209 
210## Quick Reference
211 
212| Task | Tool Slug | Key Params |
213|------|-----------|------------|
214| List all projects | `TODOIST_GET_ALL_PROJECTS` | (none) |
215| Get project | `TODOIST_GET_PROJECT` | `project_id` |
216| Create project | `TODOIST_CREATE_PROJECT` | `name`, `color`, `view_style` |
217| Update project | `TODOIST_UPDATE_PROJECT` | `project_id`, `name`, `color` |
218| List sections | `TODOIST_GET_ALL_SECTIONS` | `project_id` |
219| Create section | `TODOIST_CREATE_SECTION` | `project_id`, `name`, `order` |
220| Update section | `TODOIST_UPDATE_SECTION` | `section_id`, `name` |
221| Delete section | `TODOIST_DELETE_SECTION` | `section_id` |
222| Get all tasks | `TODOIST_GET_ALL_TASKS` | `filter`, `ids` |
223| Get task | `TODOIST_GET_TASK` | `task_id` |
224| Create task | `TODOIST_CREATE_TASK` | `content`, `project_id`, `due_string`, `priority` |
225| Bulk create tasks | `TODOIST_BULK_CREATE_TASKS` | `tasks` (array) |
226| Update task | `TODOIST_UPDATE_TASK` | `task_id`, `content`, `due_string` |
227| Complete task | `TODOIST_CLOSE_TASK` | `task_id` |
228| Reopen task | `TODOIST_REOPEN_TASK` | `task_id` |
229| Delete task | `TODOIST_DELETE_TASK` | `task_id` |
230| Completed tasks | `TODOIST_GET_COMPLETED_TASKS_BY_COMPLETION_DATE` | `since`, `until` |
231| List filters | `TODOIST_LIST_FILTERS` | `sync_token` |
232