---
canonical_url: "https://docs.composio.dev/toolkits/todoist_mcp"
markdown_url: "https://docs.composio.dev/toolkits/todoist_mcp.md"
product: "platform"
version: null
last_updated: null
---

# Todoist MCP

Todoist MCP lets agents read, create, update, organize, and complete tasks and projects through Todoist's hosted Streamable HTTP server.

- **Category:** model context protocol
- **Auth:** DCR_OAUTH
- **Composio-managed OAuth available?** No
- **Tools:** 47
- **Triggers:** 0
- **Slug:** `TODOIST_MCP`
- **Version:** 20260910_00

## Tools

### Add-comments

**Slug:** `TODOIST_MCP_ADD_COMMENTS`

Add multiple comments to tasks or projects, optionally notifying collaborators. Each comment must specify either taskId or projectId.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `comments` | array | Yes | The array of comments to add. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `comments` | array | Yes | The created comments. |
| `totalCount` | number | Yes | The total number of comments created. |
| `addedCommentIds` | array | Yes | The IDs of the added comments. |

### Add-filters

**Slug:** `TODOIST_MCP_ADD_FILTERS`

Add one or more new personal filters. Filters are saved custom views using query syntax to organize tasks.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filters` | array | Yes | The array of filters to add. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filters` | array | Yes | The created filters. |
| `totalCount` | number | Yes | The total number of filters created. |

### Add-labels

**Slug:** `TODOIST_MCP_ADD_LABELS`

Add one or more new personal labels.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `labels` | array | Yes | The array of labels to add. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `labels` | array | Yes | The created labels. |
| `totalCount` | number | Yes | The total number of labels created. |

### Add-projects

**Slug:** `TODOIST_MCP_ADD_PROJECTS`

Add one or more new projects.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `projects` | array | Yes | The array of projects to add. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `failures` | array | Yes | Projects that could not be created, with the reason for each. A failure here does not affect the other projects in the batch — do not retry the whole batch; address or drop the failed items. |
| `projects` | array | Yes | The created projects. |
| `totalCount` | number | Yes | The total number of projects created. |
| `failureCount` | number | Yes | The number of failed project creations. |
| `successCount` | number | Yes | The number of successfully created projects. |
| `totalRequested` | number | Yes | The total number of projects requested. |

### Add-reminders

**Slug:** `TODOIST_MCP_ADD_REMINDERS`

Add reminders to tasks. Supports three types: "relative" (minutes before due), "absolute" (specific date/time), or "location" (geofence-triggered). Each reminder must specify a taskId.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `reminders` | array | Yes | Array of reminders to create (max 25). Each reminder must specify a type: "relative" (minutes before due), "absolute" (specific date/time), or "location" (geofence trigger). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `reminders` | array | Yes | The created reminders. |
| `totalCount` | number | Yes | Total number of reminders created. |
| `addedReminderIds` | array | Yes | IDs of the created reminders. |

### Add-sections

**Slug:** `TODOIST_MCP_ADD_SECTIONS`

Add one or more new sections to projects.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sections` | array | Yes | The array of sections to add. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `failures` | array | Yes | Sections that could not be created, with the reason for each. A failure here does not affect the other sections in the batch — do not retry the whole batch; address or drop the failed items. |
| `sections` | array | Yes | The created sections. |
| `totalCount` | number | Yes | The total number of sections created. |
| `failureCount` | number | Yes | The number of failed section creations. |
| `successCount` | number | Yes | The number of successfully created sections. |
| `totalRequested` | number | Yes | The total number of sections requested. |

### Add-tasks

**Slug:** `TODOIST_MCP_ADD_TASKS`

Add one or more tasks to a project, section, or parent. Supports assignment to project collaborators.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tasks` | array | Yes | The array of tasks to add (max 25). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tasks` | array | Yes | The created tasks. |
| `failures` | array | Yes | Failed task creations with error details. |
| `totalCount` | number | Yes | The total number of tasks created. |
| `failureCount` | number | Yes | The number of failed task creations. |
| `successCount` | number | Yes | The number of successfully created tasks. |
| `totalRequested` | number | Yes | The total number of tasks requested. |

### Analyze-project-health

**Slug:** `TODOIST_MCP_ANALYZE_PROJECT_HEALTH`

Trigger a new health analysis for a project. Use this when the health data is stale or you want a fresh assessment. The analysis may take time to complete — use get-project-health afterward to see updated results.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `projectId` | string | Yes | The ID of the project to analyze. This triggers a new health analysis which may take some time to complete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `health` | object | Yes | The health response returned after triggering analysis. |
| `message` | string | Yes | A human-readable message about the analysis status. |
| `projectId` | string | Yes | The project ID. |

### Complete-tasks

**Slug:** `TODOIST_MCP_COMPLETE_TASKS`

Complete one or more tasks by their IDs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ids` | array | Yes | The IDs of the tasks to complete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `failures` | array | Yes | Failed task completions with error details. |
| `completed` | array | Yes | The IDs of successfully completed tasks. |
| `failureCount` | number | Yes | The number of failed task completions. |
| `successCount` | number | Yes | The number of successfully completed tasks. |
| `totalRequested` | number | Yes | The total number of tasks requested to complete. |

### Delete-object

**Slug:** `TODOIST_MCP_DELETE_OBJECT`

Delete a project, section, task, comment, label, filter, reminder, or location_reminder by its ID. Projects can be deleted whether active or archived (find archived ones via find-projects with archivedStatus); note a workspace project must be archived before it can be deleted, while personal projects can be deleted regardless.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The ID of the entity to delete. |
| `type` | string ("project" | "section" | "task" | "comment" | "label" | "filter" | "reminder" | "location_reminder") | Yes | The type of entity to delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `success` | boolean | Yes | Whether the deletion was successful. |
| `deletedEntity` | object | Yes | Information about the deleted entity. |

### Export-project-template

**Slug:** `TODOIST_MCP_EXPORT_PROJECT_TEMPLATE`

Export an existing project as a Todoist template, either as CSV content or as a shareable URL. Use it to duplicate a project, share its structure, or hand the CSV to import-project-template. To read a project rather than export it, use find-tasks instead — it returns structured tasks rather than raw CSV. Nothing is modified.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `format` | string ("file" | "url") | No | How to return the template. "file" returns the CSV content, which can be passed straight back to import-project-template. "url" returns a shareable download link instead, and is the better choice for large projects because it does not return the whole file. |
| `projectId` | string | Yes | The ID of the project to export as a template. |
| `useRelativeDates` | boolean | No | Export due dates relative to the import date (e.g. "day 3") instead of absolute dates. Defaults to false. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `format` | string ("file" | "url") | Yes | The format the template was exported in. |
| `content` | string | No | The template as CSV content. Only present when format is "file". |
| `fileUrl` | string | No | The shareable download URL. Only present when format is "url". |
| `fileName` | string | No | The generated template file name. Only present when format is "url". |
| `lineCount` | number | No | Number of rows in the exported CSV. Only present when format is "file". |

### Fetch

**Slug:** `TODOIST_MCP_FETCH`

Fetch the full contents of a task or project by its ID. The ID should be in the format "task:{id}" or "project:{id}".

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | A unique identifier for the document in the format "task:{id}" or "project:{id}". |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The ID of the fetched document. |
| `url` | string | Yes | The URL of the document. |
| `text` | string | Yes | The text content of the document. |
| `title` | string | Yes | The title of the document. |
| `metadata` | object | No | Additional metadata about the document. |

### Fetch-object

**Slug:** `TODOIST_MCP_FETCH_OBJECT`

Fetch a single task, project, comment, or section by its ID. Use this when you have a specific object ID and want to retrieve its full details. Set includeChildren to also get its direct subtasks or sub-projects.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique ID of the object to fetch. |
| `type` | string ("task" | "project" | "comment" | "section") | Yes | The type of object to fetch. |
| `includeChildren` | boolean | No | Also return the direct children of the object: subtasks for a task, sub-projects for a project. Returns childCount plus a compact list, flagging each child that has children of its own. Use this to check whether a task hides subtasks instead of a speculative find-tasks lookup. Ignored for comments and sections. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The ID of the fetched object. |
| `type` | string ("task" | "project" | "comment" | "section") | Yes | The type of object fetched. |
| `object` | string | Yes | The fetched object data. |
| `children` | array | No | Direct children only: subtasks for a task, sub-projects for a project. Completed subtasks and archived sub-projects are excluded. |
| `childCount` | number | No | The number of direct children listed in children. Only present when children were requested and the type supports them. 0 means the object definitively has none. |
| `childrenError` | string | No | Present when the children lookup failed or returned incomplete information. When no children are listed alongside it, childCount is unknown - do not read its absence as "no children". |
| `hasMoreChildren` | boolean | No | Present when the object has more than 25 direct children and the list was truncated. Page through the rest with find-tasks by parentId for subtasks, or find-projects for sub-projects. |

### Find-activity

**Slug:** `TODOIST_MCP_FIND_ACTIVITY`

Retrieve activity logs to monitor and audit changes in Todoist. Shows events from all users by default (use initiatorId to filter by specific user). To answer what someone completed in a period, including recurring task occurrences, use objectType "task", eventType "completed", and dateFrom/dateTo. For a first-person question ("what did I get done"), also set initiatorId to the current user from user-info, or the answer includes collaborators' completions. Track task completions, updates, deletions, project changes, and more with flexible filtering. Activity history availability and retention depend on the user plan.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of activity events to return. |
| `cursor` | string | No | Pagination cursor for retrieving the next page of results. |
| `dateTo` | string | No | Exclusive end of the activity range, as an ISO 8601 date or date-time. For all events on 2026-08-02, use "2026-08-03T00:00:00-04:00". Natural-language dates such as "tomorrow" are not supported. |
| `taskId` | string | No | Filter events by parent task ID (for subtask events). |
| `dateFrom` | string | No | Inclusive start of the activity range, as an ISO 8601 date or date-time. For all events on one local calendar day, use that day's start, for example "2026-08-02T00:00:00-04:00". Natural-language dates such as "tomorrow" are not supported. |
| `objectId` | string | No | Filter by specific object ID (task, project, or comment). |
| `eventType` | string ("added" | "updated" | "deleted" | "completed" | "uncompleted" | "archived" | "unarchived" | "shared" | "left") | No | Type of event to filter by. |
| `projectId` | string | No | Filter events by parent project ID. |
| `objectType` | string ("task" | "project" | "comment") | No | Type of object to filter by. |
| `initiatorId` | string | No | Filter by the user ID who initiated the event. A first-person question ("what did I complete") needs this: without it the results cover every collaborator. Get the ID from user-info when you do not already have it. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `events` | array | Yes | The activity events. |
| `hasMore` | boolean | Yes |  |
| `nextCursor` | string | No |  |
| `totalCount` | number | Yes | The total number of events in this page. |
| `appliedFilters` | object | Yes |  |

### Find-comments

**Slug:** `TODOIST_MCP_FIND_COMMENTS`

Find comments by task, project, or get a specific comment by ID. Exactly one of taskId, projectId, or commentId must be provided.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of comments to return |
| `cursor` | string | No | Pagination cursor for retrieving more results. |
| `taskId` | string | No | Find comments for a specific task. |
| `commentId` | string | No | Get a specific comment by ID. |
| `projectId` | string | No | Find comments for a specific project. Project ID should be an ID string, or the text "inbox", for inbox tasks. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `hasMore` | boolean | Yes |  |
| `comments` | array | Yes | The found comments. |
| `searchId` | string | Yes | The ID that was searched for (comment, task, or project ID). |
| `nextCursor` | string | No |  |
| `searchType` | string | Yes | The type of search performed: "single" (comment ID), "task" (task ID), or "project" (project ID). |
| `totalCount` | number | Yes | The total number of comments in this page. |

### Find-completed-tasks

**Slug:** `TODOIST_MCP_FIND_COMPLETED_TASKS`

Get completed tasks in a date range. For "what did I complete/get done" questions, use find-activity instead — it reports completion events, including every occurrence of a recurring task, which this tool does not. since/until are optional and default to a 7-day window when omitted. Includes all collaborators by default. Person-specific queries (summaries, plans, reports) require responsibleUser.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `getBy` | string ("completion" | "due") | No | The method to use to get the tasks: "completion" to get tasks by completion date (ie, when the task was actually completed), "due" to get tasks by due date (ie, when the task was due to be completed by). |
| `limit` | integer | No | The maximum number of tasks to return. |
| `since` | string | No | Optional start date for completed tasks. Format: YYYY-MM-DD. Defaults to 6 days before until (or today if until is omitted), resulting in a 7-day window. |
| `until` | string | No | Optional end date for completed tasks. Format: YYYY-MM-DD. Defaults to 6 days after since (or today if since is omitted), resulting in a 7-day window. |
| `cursor` | string | No | The cursor to get the next page of tasks (cursor is obtained from the previous call to this tool, with the same parameters). |
| `labels` | array | No | The labels to filter the tasks by |
| `parentId` | string | No | The ID of the parent task to get the tasks for. |
| `projectId` | string | No | The ID of the project to get the tasks for. Project ID should be an ID string, or the text "inbox", for inbox tasks. |
| `sectionId` | string | No | The ID of the section to get the tasks for. |
| `workspaceId` | string | No | The ID of the workspace to get the tasks for. |
| `labelsOperator` | string ("and" | "or") | No | The operator to use when filtering by labels. This will dictate whether a task has all labels, or some of them. Default is "or". |
| `responsibleUser` | string | No | Filter completed tasks assigned to this user. User ID, name, or email. For personal queries (summaries, plans, reports), set to current user from user-info to exclude collaborators. Defaults to all collaborators. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tasks` | array | Yes | The found completed tasks. |
| `hasMore` | boolean | Yes |  |
| `nextCursor` | string | No |  |
| `totalCount` | number | Yes | The total number of tasks in this page. |
| `appliedFilters` | object | Yes |  |

### Find-filters

**Slug:** `TODOIST_MCP_FIND_FILTERS`

List all personal filters or search for filters by name. Filters are saved custom views that use query syntax to organize tasks (e.g. "today & p1", "#Work & overdue").

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search` | string | No | Search for a filter by name (partial and case insensitive match). If omitted, all filters are returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filters` | array | Yes | The found filters. |
| `totalCount` | number | Yes | The total number of filters returned. |

### Find-labels

**Slug:** `TODOIST_MCP_FIND_LABELS`

List personal labels and shared labels. Personal labels have full metadata (id, name, color, order, isFavorite) and support pagination and name search (partial, case insensitive). Shared labels are labels used on tasks shared with you — they are returned as names only (no IDs or metadata). When searching, all matching personal labels are fetched across all pages and returned as a single result set (limit and cursor are ignored). When not searching, personal labels are returned with pagination.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | The maximum number of labels to return. |
| `cursor` | string | No | The cursor to get the next page of labels (cursor is obtained from the previous call to this tool, with the same parameters). Ignored when searchText is provided. |
| `searchText` | string | No | Search for a label by name (partial and case insensitive match). Supports wildcards (e.g. "work*" for prefix match). Use "\*" for a literal asterisk. If omitted, all labels are returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `labels` | array | Yes | The found personal labels. |
| `hasMore` | boolean | Yes |  |
| `nextCursor` | string | No |  |
| `totalCount` | number | Yes | The total number of labels in this page. |
| `sharedLabels` | array | Yes | Names of all shared labels visible to you. These have no IDs or metadata — use their names directly when filtering tasks. |
| `appliedFilters` | object | Yes |  |

### Find-project-collaborators

**Slug:** `TODOIST_MCP_FIND_PROJECT_COLLABORATORS`

Find Todoist users (collaborators, teammates) by name or email to look up their user ID. Use this whenever the user asks to find, look up, or identify a person — e.g. "find Carrie's user ID", "who is Ernesto", "look up a user". When projectId is omitted, searches across the collaborators of every shared project the authenticated user has access to, plus the authenticated user themselves — an empty result means the person is not a collaborator on any project you share with them, not necessarily that they do not exist in Todoist. When projectId is provided, searches only that project. Partial, case-insensitive match on name and email.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `projectId` | string | No | Optional. If provided, searches only collaborators of this project. If omitted, searches across the collaborators of all shared projects the authenticated user can access (plus the authenticated user themselves) — use this for general "find a user" / "who is X" lookups. |
| `searchTerm` | string | No | Search for a user by name or email (partial and case insensitive match). If omitted, all users are returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `totalCount` | number | Yes | The total number of users found. |
| `projectInfo` | object | No | Information about the project (only present when projectId was provided). |
| `collaborators` | array | Yes | The found users. |
| `appliedFilters` | object | Yes |  |
| `totalAvailable` | number | No | The total number of available users before the search filter was applied. |

### Find-projects

**Slug:** `TODOIST_MCP_FIND_PROJECTS`

List all projects or search for projects by name. By default only active projects are returned; use archivedStatus ('archived' or 'all') to include archived projects. When searching or when archivedStatus is 'all', all matching projects are returned (pagination is ignored). Otherwise projects are returned with pagination.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | The maximum number of projects to return. |
| `cursor` | string | No | The cursor to get the next page of projects (cursor is obtained from the previous call to this tool, with the same parameters). |
| `searchText` | string | No | Search for a project by name (partial and case insensitive match). Supports wildcards (e.g. "work*" for prefix match). Use "\*" for a literal asterisk. If omitted, all projects are returned. |
| `archivedStatus` | string ("active" | "archived" | "all") | No | Which projects to return by archive status: 'active' (default, non-archived only), 'archived' (archived only), or 'all' (both active and archived). Each project includes an isArchived field. Archived projects can be deleted via the delete-object tool (type: 'project'). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `hasMore` | boolean | Yes |  |
| `projects` | array | Yes | The found projects. |
| `nextCursor` | string | No |  |
| `totalCount` | number | Yes | The total number of projects in this page. |
| `appliedFilters` | object | Yes |  |

### Find-reminders

**Slug:** `TODOIST_MCP_FIND_REMINDERS`

Find reminders by task ID (returns all reminder types), or get a specific reminder by its ID. Use reminderId for time-based reminders and locationReminderId for location reminders.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `taskId` | string | No | Find all reminders for a specific task. Returns both time-based and location reminders. |
| `reminderId` | string | No | Get a specific time-based reminder (relative or absolute) by its ID. |
| `locationReminderId` | string | No | Get a specific location reminder by its ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `searchId` | string | Yes | The ID used for the search. |
| `reminders` | array | Yes | The found reminders (time-based and location). |
| `searchType` | string | Yes | The search type used: "task", "reminder", or "location_reminder". |
| `totalCount` | number | Yes | Total reminders in this response. |

### Find-sections

**Slug:** `TODOIST_MCP_FIND_SECTIONS`

Search for sections by name or other criteria in a project. When searching, uses server-side search to avoid fetching all sections.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `projectId` | string | Yes | The ID of the project to search sections in. Project ID should be an ID string, or the text "inbox", for inbox tasks. |
| `searchText` | string | No | Search for a section by name (partial and case insensitive match). Supports wildcards (e.g. "work*" for prefix match). Use "\*" for a literal asterisk. If omitted, all sections in the project are returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sections` | array | Yes | The found sections. |
| `totalCount` | number | Yes | The total number of sections found. |
| `appliedFilters` | object | Yes |  |

### Find-tasks

**Slug:** `TODOIST_MCP_FIND_TASKS`

Find tasks by text search, project/section/parent container, responsible user, labels, a raw Todoist filter string, or a saved filter by ID or name (filterIdOrName). At least one filter must be provided.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | The maximum number of tasks to return. |
| `cursor` | string | No | The cursor to get the next page of tasks (cursor is obtained from the previous call to this tool, with the same parameters). |
| `filter` | string | No | A raw Todoist filter query string (e.g. "today", "p1", "##Work", "(today | overdue) & p1"). Combined with other filters using AND. Cannot be used with projectId, sectionId, parentId, or filterIdOrName. |
| `labels` | array | No | The labels to filter the tasks by |
| `parentId` | string | No | Find subtasks of this parent task. |
| `projectId` | string | No | Find tasks in this project. Project ID should be an ID string, or the text "inbox", for inbox tasks. |
| `sectionId` | string | No | Find tasks in this section. |
| `searchText` | string | No | The text to search for in tasks. |
| `filterIdOrName` | string | No | The ID or name of a saved Todoist filter. The filter's query will be fetched and used to find tasks. Cannot be used with the `filter` parameter, projectId, sectionId, or parentId. |
| `labelsOperator` | string ("and" | "or") | No | The operator to use when filtering by labels. This will dictate whether a task has all labels, or some of them. Default is "or". |
| `responsibleUser` | string | No | Find tasks assigned to this user. Can be a user ID, name, or email address. The current user also includes unassigned tasks. |
| `responsibleUserFiltering` | string ("assigned" | "unassignedOrMe" | "all") | No | How to filter by responsible user when responsibleUser is not provided. "assigned" = only tasks assigned to others; "unassignedOrMe" = only unassigned tasks or tasks assigned to me; "all" = all tasks regardless of assignment. Default value will be `unassignedOrMe`. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tasks` | array | Yes | The found tasks. |
| `hasMore` | boolean | Yes |  |
| `nextCursor` | string | No |  |
| `totalCount` | number | Yes | The total number of tasks in this page. |
| `appliedFilters` | object | Yes |  |

### Find-tasks-by-date

**Slug:** `TODOIST_MCP_FIND_TASKS_BY_DATE`

Get tasks by date range. startDate='today' includes overdue items. Default responsibleUserFiltering='unassignedOrMe' excludes others' tasks.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | The maximum number of tasks to return. Default is 10. |
| `cursor` | string | No | The cursor to get the next page of tasks (cursor is obtained from the previous call to this tool, with the same parameters). |
| `labels` | array | No | The labels to filter the tasks by |
| `daysCount` | integer | No | The number of days to get the tasks for, starting from the start date. Default is 1 which means only tasks for the start date. |
| `startDate` | string | No | The start date to get the tasks for. Format: YYYY-MM-DD, or 'today', which by default also includes overdue tasks. |
| `overdueOption` | string ("overdue-only" | "include-overdue" | "exclude-overdue") | No | How to handle overdue tasks. 'overdue-only' to get only overdue tasks, 'include-overdue' to include overdue tasks along with tasks for the specified date(s), and 'exclude-overdue' to exclude overdue tasks. Default is 'include-overdue'. |
| `labelsOperator` | string ("and" | "or") | No | The operator to use when filtering by labels. This will dictate whether a task has all labels, or some of them. Default is "or". |
| `responsibleUser` | string | No | Filter tasks assigned to this user. User ID, name, or email. The current user also includes unassigned tasks. |
| `responsibleUserFiltering` | string ("assigned" | "unassignedOrMe" | "all") | No | Filter when responsibleUser is omitted. 'assigned'=assigned to others; 'unassignedOrMe'=unassigned+mine; 'all'=everyone. Default: 'unassignedOrMe'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tasks` | array | Yes | The found tasks. |
| `hasMore` | boolean | Yes |  |
| `nextCursor` | string | No |  |
| `totalCount` | number | Yes | The total number of tasks in this page. |
| `appliedFilters` | object | Yes |  |

### Get-overview

**Slug:** `TODOIST_MCP_GET_OVERVIEW`

Get a Markdown overview. If no projectId is provided, shows all projects with hierarchy and sections (useful for navigation). If projectId is provided, shows detailed overview of that specific project including all tasks grouped by sections.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `projectId` | string | No | Optional project ID. If provided, shows detailed overview of that project. If omitted, shows overview of all projects. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string ("account_overview" | "project_overview") | Yes | The type of overview returned. |
| `inbox` | object | No | Inbox information (account overview only). |
| `stats` | object | No | Statistics object (project overview only). |
| `tasks` | array | No | List of tasks (project overview only). |
| `project` | object | No | Project details (project overview only). |
| `projects` | array | No | List of projects with hierarchy, folders, and ordering (account overview only). |
| `sections` | array | No | List of sections (project overview only). |
| `totalTasks` | number | No | Total number of tasks. |
| `projectInfo` | object | No | Project information (project overview only). |
| `totalProjects` | number | No | Total number of projects (account overview only). |
| `totalSections` | number | No | Total number of sections (project overview only). |
| `hasNestedProjects` | boolean | No | Whether account has nested projects (account overview only). |
| `tasksWithoutSection` | number | No | Number of tasks not in any section (project overview only). |

### Get-productivity-stats

**Slug:** `TODOIST_MCP_GET_PRODUCTIVITY_STATS`

Get comprehensive productivity statistics including daily/weekly completion breakdowns, goal streaks (current, last, max), karma score and trends, and historical karma data. Useful for productivity analysis and tracking goal progress. Reports counts, streaks and karma only, never the tasks themselves — for "what did I complete", use find-activity.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `goals` | object | Yes | Goal and streak information. |
| `karma` | number | Yes | Current karma score. |
| `daysItems` | array | Yes | Daily completion breakdown (most recent days). |
| `weekItems` | array | Yes | Weekly completion breakdown (most recent weeks). |
| `karmaTrend` | string | Yes | Karma trend direction (e.g., "up" or "down"). |
| `projectColors` | object | Yes | Map of project ID to color key. |
| `completedCount` | number | Yes | Total number of completed tasks (all-time). |
| `karmaGraphData` | array | Yes | Historical karma data points for graphing. |
| `karmaLastUpdate` | number | Yes | Timestamp of the last karma update. |
| `karmaUpdateReasons` | array | Yes | Recent karma change events with reasons. |

### Get-project-activity-stats

**Slug:** `TODOIST_MCP_GET_PROJECT_ACTIVITY_STATS`

Get daily and optional weekly task completion counts for a project over a configurable time window (1-12 weeks). Useful for identifying completion trends and patterns.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `weeks` | integer | No | Number of weeks of activity data to retrieve (1-12, default 2). |
| `projectId` | string | Yes | The ID of the project to get activity stats for. |
| `includeWeeklyCounts` | boolean | No | Include weekly rollup counts alongside daily counts. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `dayItems` | array | Yes | Daily task completion counts. |
| `projectId` | string | Yes | The project ID. |
| `weekItems` | array | No | Weekly completion rollups. Only included when includeWeeklyCounts is true. |

### Get-project-health

**Slug:** `TODOIST_MCP_GET_PROJECT_HEALTH`

Get a comprehensive health assessment for a project including completion progress, health status (EXCELLENT, ON_TRACK, AT_RISK, CRITICAL), and optional detailed context with project metrics and task-level data. Use includeContext=true for that full detail.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `projectId` | string | Yes | The ID of the project to check health for. |
| `includeContext` | boolean | No | Include detailed health context with project metrics and task-level data. May produce large output for projects with many tasks. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `health` | object | Yes | Project health assessment. |
| `context` | object | No | Detailed project context with metrics and task data. Only included when includeContext is true. |
| `progress` | object | Yes | Project completion progress. |
| `projectId` | string | Yes | The project ID. |
| `projectName` | string | Yes | The project name. |

### Get-workspace-insights

**Slug:** `TODOIST_MCP_GET_WORKSPACE_INSIGHTS`

Get aggregated health and progress insights across all projects in a workspace. Accepts workspace name or ID, with optional project ID filtering. Useful for a cross-project health overview.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `projectIds` | array | No | Optional list of project IDs to scope insights to specific projects. |
| `workspaceIdOrName` | string | Yes | The workspace ID or name. Supports exact ID, exact name match (case-insensitive), or unique partial name match. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `workspaceId` | string | Yes | The resolved workspace ID. |
| `workspaceName` | string | Yes | The resolved workspace name. |
| `projectInsights` | array | Yes | Health and progress insights for each project in the workspace. |

### Import-project-template

**Slug:** `TODOIST_MCP_IMPORT_PROJECT_TEMPLATE`

Import a template into an existing project, adding its tasks, sections and comments to whatever is already there. Source it by template ID/URL or by passing CSV content from export-project-template. To start a new project from a template, create the project with add-projects first, then import into it. This writes immediately and cannot be undone, so only run it against a project the user named.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `locale` | string | No | Locale for the imported content when using `templateId`. Defaults to "en". |
| `projectId` | string | Yes | The ID of the existing project to import the template into. |
| `templateId` | string | No | The template to import — either a gallery slug ("product-launch"), a personal template ID ("UT_28Ex..."), or a full Todoist template URL, which is reduced to the ID automatically. Gallery templates work for anyone; personal templates only for the account that owns them. There is no way to list templates through this server, so only use the ID or URL the user supplied. Provide either this or `csvFileContent`, not both. |
| `csvFileContent` | string | No | Raw CSV template content, as produced by export-project-template. Provide either this or `templateId`, not both. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tasks` | array | Yes | Tasks created by the import. |
| `comments` | array | Yes | Comments created by the import. |
| `sections` | array | Yes | Sections created by the import. |
| `totalCount` | number | Yes | The total number of objects created by the import. |

### List-workspaces

**Slug:** `TODOIST_MCP_LIST_WORKSPACES`

Get all workspaces for the authenticated user. Returns workspace details including ID, name, plan type (STARTER/BUSINESS), user role (ADMIN/MEMBER/GUEST), link sharing settings, guest permissions, creation date, and creator ID.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | The type of the response. |
| `count` | number | Yes | The total number of workspaces. |
| `workspaces` | array | Yes | List of workspaces. |

### Manage-assignments

**Slug:** `TODOIST_MCP_MANAGE_ASSIGNMENTS`

Bulk assignment operations for multiple tasks. Supports assign, unassign, and reassign operations with atomic rollback on failures.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `dryRun` | boolean | No | If true, validates operations without executing them. |
| `taskIds` | array | Yes | The IDs of the tasks to operate on (max 50). |
| `operation` | string ("assign" | "unassign" | "reassign") | Yes | The assignment operation to perform. |
| `responsibleUser` | string | No | The user to assign tasks to. Can be "me" (assigns to current user), a user ID, name, or email. Required for assign and reassign operations. |
| `fromAssigneeUser` | string | No | For reassign operations: the current assignee to reassign from. Can be user ID, name, or email. Optional - if not provided, reassigns from any current assignee. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `results` | array | Yes | Results of the assignment operations. |
| `summary` | object | No | Summary of the operation. |

### Project-management

**Slug:** `TODOIST_MCP_PROJECT_MANAGEMENT`

Archive or unarchive a project by its ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string ("archive" | "unarchive") | Yes | The action to perform on the project. |
| `projectId` | string | Yes | The ID of the project. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project` | object | Yes | The updated project. |
| `success` | boolean | Yes | Whether the action was successful. |

### Project-move

**Slug:** `TODOIST_MCP_PROJECT_MOVE`

Move a project between personal and workspace contexts.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string ("move-to-workspace" | "move-to-personal") | Yes | The action to perform on the project. |
| `folderId` | string | No | Optional target folder ID within the workspace. |
| `projectId` | string | Yes | The ID of the project to move. |
| `visibility` | string ("restricted" | "team" | "public") | No | Optional access visibility for the project in the workspace (restricted, team, or public). |
| `workspaceId` | string | No | The target workspace ID. Required when action is move-to-workspace. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project` | object | Yes | The moved project. |
| `success` | boolean | Yes | Whether the move was successful. |

### Reorder-objects

**Slug:** `TODOIST_MCP_REORDER_OBJECTS`

Reorder sibling projects or sections, and optionally move projects to a new parent. For projects: set order to reorder siblings, and/or set parentId to move under a new parent (use "root" for top level). For sections: set order to reorder within a project.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string ("project" | "section") | Yes | The type of entity to reorder. "project" reorders sibling projects within the same parent (and can move projects to a new parent). "section" reorders sections within the same project. |
| `items` | array | Yes | The items to reorder or move. Each item must have at least order or parentId. Items with parentId will be moved first, then items with order will be reordered. All items being reordered should be siblings for predictable results. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string ("project" | "section") | Yes | The type of entity that was reordered/moved. |
| `success` | boolean | Yes | Whether the operation was successful. |
| `movedCount` | number | Yes | The number of entities moved to a new parent. |
| `affectedIds` | array | Yes | The IDs of all affected entities. |
| `reorderedCount` | number | Yes | The number of entities reordered. |

### Reschedule-tasks

**Slug:** `TODOIST_MCP_RESCHEDULE_TASKS`

Reschedule tasks to new dates while preserving recurring schedules. Unlike update-tasks (which replaces the entire due string and can wipe recurrence), this tool changes only the date, keeping recurrence patterns intact. Use this when moving recurring tasks to a different date without altering their repeat pattern.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tasks` | array | Yes | The tasks to reschedule with their new dates. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tasks` | array | Yes | The rescheduled tasks. |
| `totalCount` | number | Yes | The total number of tasks rescheduled. |
| `rescheduledTaskIds` | array | Yes | The IDs of the rescheduled tasks. |

### Search

**Slug:** `TODOIST_MCP_SEARCH`

Search across tasks and projects in Todoist. Returns a list of relevant results with IDs, titles, and URLs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | The search query string to find tasks and projects. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `results` | array | Yes | The search results. |
| `totalCount` | number | Yes | Total number of results found. |

### Uncomplete-tasks

**Slug:** `TODOIST_MCP_UNCOMPLETE_TASKS`

Uncomplete (reopen) one or more completed tasks by their IDs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ids` | array | Yes | The IDs of the tasks to uncomplete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `failures` | array | Yes | Failed task uncompletion with error details. |
| `uncompleted` | array | Yes | The IDs of successfully uncompleted tasks. |
| `failureCount` | number | Yes | The number of failed task uncompletions. |
| `successCount` | number | Yes | The number of successfully uncompleted tasks. |
| `totalRequested` | number | Yes | The total number of tasks requested to uncomplete. |

### Update-comments

**Slug:** `TODOIST_MCP_UPDATE_COMMENTS`

Update multiple existing comments with new content.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `comments` | array | Yes | The comments to update. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `comments` | array | Yes | The updated comments. |
| `totalCount` | number | Yes | The total number of comments updated. |
| `appliedOperations` | object | Yes | Summary of operations performed. |
| `updatedCommentIds` | array | Yes | The IDs of the updated comments. |

### Update-filters

**Slug:** `TODOIST_MCP_UPDATE_FILTERS`

Update one or more existing personal filters with new values.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filters` | array | Yes | The filters to update. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filters` | array | Yes | The updated filters. |
| `totalCount` | number | Yes | The total number of filters updated. |
| `updatedFilterIds` | array | Yes | The IDs of the updated filters. |
| `appliedOperations` | object | Yes | Summary of operations performed. |

### Update-labels

**Slug:** `TODOIST_MCP_UPDATE_LABELS`

Update one or more existing labels. Personal labels (identified by ID) can have their name, color, order, and favorite flag updated. Shared labels (identified by name) can only be renamed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `labels` | array | Yes | The labels to update. Use labelType="personal" with an ID to update a personal label, or labelType="shared" with name+newName to rename a shared label. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `totalCount` | number | Yes | The total number of successful operations (personal + shared). |
| `updatedLabels` | array | Yes | The updated personal labels. |
| `appliedOperations` | object | Yes | Summary of operations performed. |
| `renamedSharedLabels` | array | Yes | The shared labels that were renamed. |

### Update-projects

**Slug:** `TODOIST_MCP_UPDATE_PROJECTS`

Update multiple existing projects with new values.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `projects` | array | Yes | The projects to update. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `failures` | array | Yes | Projects that could not be updated, with the reason for each. A failure here does not affect the other projects in the batch — do not retry the whole batch; address or drop the failed items. |
| `projects` | array | Yes | The updated projects. |
| `totalCount` | number | Yes | The total number of projects updated. |
| `appliedOperations` | object | Yes | Summary of operations performed. |
| `updatedProjectIds` | array | Yes | The IDs of the updated projects. |

### Update-reminders

**Slug:** `TODOIST_MCP_UPDATE_REMINDERS`

Update existing reminders. Each reminder must specify its type ("relative", "absolute", or "location") and ID. Only include fields that need to change.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `reminders` | array | Yes | Array of reminders to update (max 25). Each must include the reminder type and ID. Only include fields that need to change. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `reminders` | array | Yes | The updated reminders. |
| `totalCount` | number | Yes | Total reminders updated. |
| `updatedReminderIds` | array | Yes | IDs of updated reminders. |

### Update-sections

**Slug:** `TODOIST_MCP_UPDATE_SECTIONS`

Update multiple existing sections with new values.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sections` | array | Yes | The sections to update. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sections` | array | Yes | The updated sections. |
| `totalCount` | number | Yes | The total number of sections updated. |
| `updatedSectionIds` | array | Yes | The IDs of the updated sections. |

### Update-tasks

**Slug:** `TODOIST_MCP_UPDATE_TASKS`

Update existing tasks including content, dates, priorities, and assignments. Send only the fields that change.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tasks` | array | Yes | The tasks to update (max 25). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tasks` | array | Yes | The updated tasks. |
| `failures` | array | Yes | Tasks that could not be updated, with the reason for each. A failure here does not affect the other tasks in the batch. |
| `totalCount` | number | Yes | The total number of tasks updated. |
| `updatedTaskIds` | array | Yes | The IDs of the updated tasks. |
| `appliedOperations` | object | Yes | Summary of operations performed. |

### User-info

**Slug:** `TODOIST_MCP_USER_INFO`

Get comprehensive user information including user ID, full name, email, timezone with current local time, week start day preferences, current week dates, daily/weekly goal progress, and user plan (Free/Pro/Business).

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `plan` | string ("Todoist Free" | "Todoist Pro" | "Todoist Business") | Yes | The user plan. |
| `type` | string | Yes | The type of the response. |
| `email` | string | Yes | The email address of the user. |
| `userId` | string | Yes | The user ID. |
| `fullName` | string | Yes | The full name of the user. |
| `startDay` | number | Yes | The start day of the week (1 = Monday, 7 = Sunday). |
| `timezone` | string | Yes | The timezone of the user. |
| `dailyGoal` | number | Yes | The daily goal for task completions. |
| `weeklyGoal` | number | Yes | The weekly goal for task completions. |
| `weekEndDate` | string | Yes | The end date of the current week (YYYY-MM-DD). |
| `startDayName` | string | Yes | The name of the start day. |
| `weekStartDate` | string | Yes | The start date of the current week (YYYY-MM-DD). |
| `completedToday` | number | Yes | The number of tasks completed today. |
| `currentLocalTime` | string | Yes | The current local time of the user. |
| `currentWeekNumber` | number | Yes | The current week number of the year. |

### View-attachment

**Slug:** `TODOIST_MCP_VIEW_ATTACHMENT`

View a file attachment from a Todoist comment. Pass the fileUrl from a comment's fileAttachment field. Supports images (returned inline), text files (returned as text), and binary files like PDFs (returned as embedded resources).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fileUrl` | string | Yes | The URL of the attachment file to view. Get this from the fileUrl field in a comment's fileAttachment. |