### Project and Section Setup Examples

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Examples of natural language commands for setting up projects and sections within Todoist.

```natural_language
Show me all my projects
```

```natural_language
Create a new project called 'Work Tasks'
```

```natural_language
Create a section called 'In Progress' in project 12345
```

```natural_language
Show me sections in the Work Tasks project
```

--------------------------------

### Install Todoist MCP Server via CLI

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Use this command to add the Todoist MCP server to your client, specifying the API token as an environment variable. This is for users not using the Claude Desktop one-click install.

```bash
claude mcp add todoist -e TODOIST_API_TOKEN=your_token -- npx @greirson/mcp-todoist
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Install all necessary Node.js dependencies for the project using npm.

```bash
# Install dependencies
npm install
```

--------------------------------

### Task Creation and Management Examples

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Examples of natural language commands for creating, updating, and managing tasks in Todoist, including due dates, priorities, labels, and durations.

```natural_language
Create task 'Team Meeting' in project 12345
```

```natural_language
Add task 'Review PR' due tomorrow with labels ['Code Review', 'Urgent']
```

```natural_language
Create high priority task with deadline 2024-12-25
```

```natural_language
Update meeting task to be in section 67890
```

```natural_language
Mark the PR review task as complete
```

```natural_language
Create task 'Deep work session' with 90 minute duration
```

```natural_language
Update task 'Meeting' to have a 2 day duration
```

```natural_language
Get task with ID 1234567890
```

```natural_language
Update task ID 1234567890 to priority 4
```

```natural_language
Complete task with ID 1234567890
```

```natural_language
Reopen task with ID 1234567890
```

```natural_language
Delete task ID 1234567890
```

--------------------------------

### Install MCP Todoist

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Ensure the MCP Todoist package is installed globally using npm. This is a prerequisite for using the tools.

```bash
npm list -g @greirson/mcp-todoist
```

--------------------------------

### Dry-Run Mode Example Output

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

This example demonstrates the output when dry-run mode is enabled. Operations that would modify data are simulated and prefixed with '[DRY-RUN]'. Read operations still use real API data.

```text
You: "Create a task called 'Test Task' in my Work project"

Response:
[DRY-RUN] Dry-run mode enabled - mutations will be simulated
[DRY-RUN] Would create task: "Test Task" in project 2203306141, section none

Task created successfully (simulated):
ID: 100001
Title: Test Task
Project: Work (2203306141)
Priority: 4 (Normal)
```

--------------------------------

### Get All Projects

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieve a list of all projects accessible to the user. This action does not require any parameters.

```json
{
  "action": "get"
}
```

--------------------------------

### Install Todoist MCP Server for Claude

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Use this command to add the Todoist MCP server to your Claude environment, providing your Todoist API token.

```bash
claude mcp add todoist -e TODOIST_API_TOKEN=your_api_token_here -- npx @greirson/mcp-todoist
```

--------------------------------

### Get user settings

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieves the user's account settings, such as theme preferences and date format.

```json
{
  "action": "settings"
}
```

--------------------------------

### Get Sections for a Project

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieve all sections within a specified project. Requires the project ID.

```json
{
  "action": "get",
  "project_id": "2203306141"
}
```

--------------------------------

### Create Todoist Task with Full Attributes

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Example of creating a Todoist task with detailed attributes including content, description, due date, priority, project, labels, and duration.

```json
{
  "action": "create",
  "content": "Review quarterly report",
  "description": "Check all financial metrics and prepare summary",
  "due_string": "tomorrow at 2pm",
  "priority": 1,
  "project_id": "2203306141",
  "labels": ["work", "urgent"],
  "duration": 90,
  "duration_unit": "minute"
}
```

--------------------------------

### Get user profile info

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieves detailed information about the authenticated user's profile.

```json
{
  "action": "info"
}
```

--------------------------------

### Get Todoist Project Notes

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Retrieve all notes associated with a specific project. Requires the project ID.

```json
{"action": "get", "project_id": "123"}
```

--------------------------------

### Get Project Collaborators

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieve a list of collaborators for a specific project. Requires the project ID.

```json
{
  "action": "collaborators",
  "project_id": "2203306141"
}
```

--------------------------------

### Project Management API

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Manages Todoist projects with create, get, update, delete, archive, and collaborators actions.

```APIDOC
## Project Management API

### Description
Manages Todoist projects with create, get, update, delete, archive, and collaborators actions.

### Create a new project

#### Request Body
- **action** (string) - Required - "create"
- **name** (string) - Required - The name of the project.
- **color** (string) - Optional - Project color (e.g., "blue", "red").
- **view_style** (string) - Optional - View style (e.g., "list", "board").
- **is_favorite** (boolean) - Optional - Whether the project is a favorite.

### Request Example
```json
{
  "action": "create",
  "name": "Q1 Planning",
  "color": "blue",
  "view_style": "board",
  "is_favorite": true
}
```

### Create a sub-project

#### Request Body
- **action** (string) - Required - "create"
- **name** (string) - Required - The name of the sub-project.
- **parent_id** (string) - Required - The ID of the parent project.
- **color** (string) - Optional - Project color.

### Request Example
```json
{
  "action": "create",
  "name": "Marketing Tasks",
  "parent_id": "2203306141",
  "color": "green"
}
```

### Get all projects

#### Request Body
- **action** (string) - Required - "get"

### Request Example
```json
{
  "action": "get"
}
```

### Update project

#### Request Body
- **action** (string) - Required - "update"
- **project_id** (string) - Required - The ID of the project to update.
- **name** (string) - Optional - New name for the project.
- **color** (string) - Optional - New color for the project.

### Request Example
```json
{
  "action": "update",
  "project_id": "2203306141",
  "name": "Q1 Planning 2024",
  "color": "red"
}
```

### Archive a project

#### Request Body
- **action** (string) - Required - "archive"
- **project_name** (string) - Required - The name of the project to archive.
- **archived** (boolean) - Required - Set to true to archive.

### Request Example
```json
{
  "action": "archive",
  "project_name": "Old Project",
  "archived": true
}
```

### Get project collaborators

#### Request Body
- **action** (string) - Required - "collaborators"
- **project_id** (string) - Required - The ID of the project.

### Request Example
```json
{
  "action": "collaborators",
  "project_id": "2203306141"
}
```

### Delete a project

#### Request Body
- **action** (string) - Required - "delete"
- **project_id** (string) - Required - The ID of the project to delete.

### Request Example
```json
{
  "action": "delete",
  "project_id": "2203306141"
}
```
```

--------------------------------

### Todoist Project API

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Manage Todoist projects - create, read, update, delete, archive, or get collaborators.

```APIDOC
## Todoist Project API

### Description
Manage Todoist projects - create, read, update, delete, archive, or get collaborators.

### Actions

- **create**: Create a new project.
- **get**: List all projects.
- **update**: Update project properties.
- **delete**: Delete a project and all its tasks.
- **archive**: Archive or unarchive a project.
- **collaborators**: Get collaborators for a shared project.

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body

- **action** (string) - Required - One of: create, get, update, delete, archive, collaborators
- **name** (string) - Required for create, Optional for update - Project name.
- **project_id** (string) - Optional - Project ID (takes precedence over project_name).
- **project_name** (string) - Optional - Project name for search.
- **color** (string) - Optional - Project color (e.g., 'red', 'blue', 'green').
- **description** (string) - Optional - Project description.
- **view_style** (string) - Optional - 'list' or 'board'.
- **is_favorite** (boolean) - Optional - Favorite status.
- **parent_id** (string) - Optional - Parent project ID (for sub-projects).
- **archived** (boolean) - Optional - true to archive, false to unarchive.

### Request Example
```json
{
  "action": "create",
  "name": "Work Tasks",
  "color": "blue",
  "view_style": "board"
}
```

```json
{
  "action": "archive",
  "project_name": "Old Project",
  "archived": true
}
```

```json
{
  "action": "collaborators",
  "project_id": "123"
}
```

### Response
#### Success Response (200)
Details depend on the action performed. For 'get', it would be a list of projects. For 'create' or 'update', it might be the updated project object.
```

--------------------------------

### Reminder Management Commands (Pro/Business)

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Manage reminders, including showing all reminders, getting reminders for specific tasks, creating new reminders (absolute or relative to due date), updating, and deleting reminders.

```bash
"Show me all my reminders"
```

```bash
"Get reminders for task 'Team Meeting'"
```

```bash
"Create a reminder for task 'Review PR' 30 minutes before due"
```

```bash
"Create an absolute reminder for task 12345 at 2024-12-25T09:00:00Z"
```

```bash
"Update reminder 67890 to trigger at 10:00 instead"
```

```bash
"Delete reminder 67890"
```

--------------------------------

### Get activity within a date range

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieves activity log entries within a specified date range (since and until). Requires Pro or Business plan.

```json
{
  "action": "by_date",
  "since": "2024-01-01",
  "until": "2024-01-31"
}
```

--------------------------------

### Get Todoist User Information

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Fetch basic user profile information, including name and email, or retrieve productivity statistics like karma and streaks.

```json
{"action": "info"}
```

```json
{"action": "stats"}
```

--------------------------------

### Get activity for a specific project

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieves activity log entries filtered by a specific project ID, with a limit on the number of results. Requires Pro or Business plan.

```json
{
  "action": "by_project",
  "project_id": "2203306141",
  "limit": 20
}
```

--------------------------------

### Get Todoist Activity Logs

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Retrieve activity entries based on object type and event type. Requires Pro/Business subscription. Filters can include project ID or date range.

```json
{"action": "get", "object_type": "item", "event_type": "completed"}
```

```json
{"action": "by_project", "project_id": "123", "limit": 20}
```

--------------------------------

### Get activity entries

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieves activity log entries, with options to filter by object type, event type, and limit the number of results. Requires Pro or Business plan.

```json
{
  "action": "get",
  "object_type": "item",
  "event_type": "completed",
  "limit": 50
}
```

--------------------------------

### Get All Shared Labels - Todoist Business

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Use this action to retrieve all shared labels within a Todoist Business workspace. No specific setup is required beyond having the necessary permissions.

```json
// Get all shared labels
{
  "action": "get"
}
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Change the current directory to the cloned mcp-todoist project folder.

```bash
# Navigate to directory
cd mcp-todoist
```

--------------------------------

### Build MCPB Package

Source: https://github.com/greirson/mcp-todoist/blob/main/mcpb/README.md

Run this command from the project root to build the Todoist MCPB package. The output will be a `todoist-mcp.mcpb` file.

```bash
npm run build:mcpb
```

--------------------------------

### Build the Project

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Compile and build the project using the npm build script.

```bash
# Build the project
npm run build
```

--------------------------------

### Todoist User API

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Get Todoist user information and productivity stats.

```APIDOC
## POST /api/todoist/user

### Description
Retrieves user profile information, productivity statistics, and settings.

### Method
POST

### Endpoint
/api/todoist/user

### Parameters
#### Request Body
- **action** (string) - Required - The action to perform: 'info', 'stats', or 'settings'.

### Request Example
```json
{
  "action": "info"
}
```

### Response
#### Success Response (200)
- **user_info** (object) - User profile details (name, email, timezone) for 'info' action.
- **productivity_stats** (object) - Karma, streaks, etc. for 'stats' action.
- **user_settings** (object) - Theme, date format, etc. for 'settings' action.

#### Response Example
```json
{
  "action": "info",
  "user_info": {
    "id": "user123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "timezone": "UTC"
  }
}
```
```

--------------------------------

### Get notifications

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Fetches a list of notifications for the user, with an optional limit on the number of results.

```json
{
  "action": "notifications",
  "limit": 20
}
```

--------------------------------

### Create a New Project

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Create a new project with specified name, color, view style, and favorite status. This action is used for top-level project creation.

```json
{
  "action": "create",
  "name": "Q1 Planning",
  "color": "blue",
  "view_style": "board",
  "is_favorite": true
}
```

--------------------------------

### Todoist Quick Add Tool

Source: https://github.com/greirson/mcp-todoist/blob/main/CLAUDE.md

A new MCP tool for creating tasks via natural language input.

```typescript
todoist_task_quick_add tool
```

--------------------------------

### Get Todoist label statistics

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Retrieve statistics on label usage. No parameters are required for this action.

```json
{"action": "stats"}
```

--------------------------------

### Check Formatting

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Verify that the codebase adheres to the project's defined code style without making changes.

```bash
# Check formatting
npm run format:check
```

--------------------------------

### Get collaborators for a Todoist project

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Retrieve a list of collaborators for a shared project using its ID.

```json
{"action": "collaborators", "project_id": "123"}
```

--------------------------------

### Create a new Todoist project

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Use this action to create a new project. Specify the name and optionally a color and view style.

```json
{"action": "create", "name": "Work Tasks", "color": "blue", "view_style": "board"}
```

--------------------------------

### Create Configuration Directory

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

On macOS/Linux, you may need to create the configuration directory if it does not exist. This is necessary for storing configuration files.

```bash
mkdir -p ~/.config
```

--------------------------------

### Run Tests

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Execute the project's test suite using the npm test script.

```bash
# Run tests
npm run test
```

--------------------------------

### Get Specific Todoist Task by ID

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieve a single Todoist task by its unique identifier.

```json
{
  "action": "get",
  "task_id": "7025693456"
}
```

--------------------------------

### Create a Sub-Project

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Create a new project that is a sub-project of an existing project. Requires the name of the new sub-project and the ID of its parent project.

```json
{
  "action": "create",
  "name": "Marketing Tasks",
  "parent_id": "2203306141",
  "color": "green"
}
```

--------------------------------

### Comment Management API

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Manages comments on tasks and projects with create, get, update, and delete operations.

```APIDOC
## Comment Management API

### Description
Manages comments on tasks and projects with create, get, update, and delete operations.

### Create a comment on a task

#### Request Body
- **action** (string) - Required - "create"
- **task_id** (string) - Required - The ID of the task.
- **content** (string) - Required - The content of the comment.

### Request Example
```json
{
  "action": "create",
  "task_id": "7025693456",
  "content": "Updated the design mockups. Please review."
}
```

### Create a comment on a project

#### Request Body
- **action** (string) - Required - "create"
- **project_id** (string) - Required - The ID of the project.
- **content** (string) - Required - The content of the comment.

### Request Example
```json
{
  "action": "create",
  "project_id": "2203306141",
  "content": "Project kickoff scheduled for Monday."
}
```

### Get comments for a task

#### Request Body
- **action** (string) - Required - "get"
- **task_id** (string) - Required - The ID of the task.

### Request Example
```json
{
  "action": "get",
  "task_id": "7025693456"
}
```

### Update a comment

#### Request Body
- **action** (string) - Required - "update"
- **comment_id** (string) - Required - The ID of the comment to update.
- **content** (string) - Required - The new content of the comment.

### Request Example
```json
{
  "action": "update",
  "comment_id": "3456789012",
  "content": "Updated comment text with new information."
}
```

### Delete a comment

#### Request Body
- **action** (string) - Required - "delete"
- **comment_id** (string) - Required - The ID of the comment to delete.

### Request Example
```json
{
  "action": "delete",
  "comment_id": "3456789012"
}
```
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Execute the test suite and generate a code coverage report.

```bash
# Run tests with coverage
npm run test:coverage
```

--------------------------------

### Create a project note

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Creates a new note associated with a specific project, including multi-line content.

```json
{
  "action": "create",
  "project_id": "2203306141",
  "content": "Project kickoff notes:\n- Goal: Launch by Q2\n- Team: 5 members\n- Budget: $50k"
}
```

--------------------------------

### Get Todoist Tasks

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Retrieve tasks using filters and priority. Useful for querying specific tasks.

```json
{"action": "get", "filter": "today", "priority": 1}
```

--------------------------------

### Watch for Changes and Rebuild

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Run the build process in watch mode, which automatically rebuilds the project whenever source files change.

```bash
# Watch for changes and rebuild
npm run watch
```

--------------------------------

### Get Label Statistics

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieve statistics on label usage. This action is useful for analytics and understanding how labels are applied.

```json
{
  "action": "stats"
}
```

--------------------------------

### Invite user to a project

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Sends an invitation to a specified email address to join a particular project. Requires appropriate permissions.

```json
{
  "action": "invite",
  "project_id": "2203306141",
  "email": "colleague@example.com"
}
```

--------------------------------

### List available backups

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Lists all available automatic backups for the account. Requires Pro or Business plan.

```json
{
  "action": "list"
}
```

--------------------------------

### Get completed tasks

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieves a list of completed tasks, with options to filter by project ID and limit the number of results.

```json
{
  "action": "get",
  "project_id": "2203306141",
  "limit": 50
}
```

--------------------------------

### Create Todoist Reminders

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Create reminders for tasks using relative or absolute timing. For relative reminders, specify `minute_offset`. For absolute reminders, provide `due_date` in ISO format. Requires a Pro/Business plan.

```json
{"action": "create", "task_id": "123", "type": "relative", "minute_offset": 30}
```

```json
{"action": "create", "task_id": "123", "type": "absolute", "due_date": "2024-12-25T09:00:00Z"}
```

--------------------------------

### Label Management API

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Manages Todoist labels with create, get, update, delete, and stats actions for usage analytics.

```APIDOC
## Label Management API

### Description
Manages Todoist labels with create, get, update, delete, and stats actions for usage analytics.

### Create a label

#### Request Body
- **action** (string) - Required - "create"
- **name** (string) - Required - The name of the label.
- **color** (string) - Optional - Label color.
- **is_favorite** (boolean) - Optional - Whether the label is a favorite.

### Request Example
```json
{
  "action": "create",
  "name": "urgent",
  "color": "red",
  "is_favorite": true
}
```

### Get all labels

#### Request Body
- **action** (string) - Required - "get"

### Request Example
```json
{
  "action": "get"
}
```

### Update label

#### Request Body
- **action** (string) - Required - "update"
- **label_name** (string) - Required - The current name of the label.
- **color** (string) - Optional - New color for the label.
- **name** (string) - Optional - New name for the label.

### Request Example
```json
{
  "action": "update",
  "label_name": "urgent",
  "color": "orange",
  "name": "high-priority"
}
```

### Delete label

#### Request Body
- **action** (string) - Required - "delete"
- **label_id** (string) - Required - The ID of the label to delete.

### Request Example
```json
{
  "action": "delete",
  "label_id": "2156154810"
}
```

### Get label usage statistics

#### Request Body
- **action** (string) - Required - "stats"

### Request Example
```json
{
  "action": "stats"
}
```
```

--------------------------------

### Enhanced Project Create Parameters

Source: https://github.com/greirson/mcp-todoist/blob/main/CLAUDE.md

Extends the project creation functionality to include `parent_id`, `description`, and `view_style` for richer project metadata and sub-projects.

```typescript
parent_id, description, view_style
```

--------------------------------

### Get Todoist Notifications

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Retrieve live notifications from Todoist, optionally specifying a `limit` for the number of notifications to fetch. This is useful for real-time updates.

```json
{"action": "notifications", "limit": 10}
```

--------------------------------

### Clone Repository

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Clone the MCP Todoist repository from GitHub to your local machine.

```bash
# Clone the repository
git clone https://github.com/greirson/mcp-todoist.git
```

--------------------------------

### Get completed tasks by date range

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieves completed tasks within a specified date range (since and until), with a limit on the number of results.

```json
{
  "action": "get",
  "since": "2024-01-01",
  "until": "2024-01-31",
  "limit": 100
}
```

--------------------------------

### Format Code

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Format the codebase according to the project's defined code style.

```bash
# Format code
npm run format
```

--------------------------------

### Section Management API

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Manages sections within projects including create, get, update, delete, move, reorder, archive, and unarchive operations.

```APIDOC
## Section Management API

### Description
Manages sections within projects including create, get, update, delete, move, reorder, archive, and unarchive operations.

### Create a section

#### Request Body
- **action** (string) - Required - "create"
- **project_id** (string) - Required - The ID of the project.
- **name** (string) - Required - The name of the section.
- **order** (integer) - Optional - The order of the section within the project.

### Request Example
```json
{
  "action": "create",
  "project_id": "2203306141",
  "name": "In Progress",
  "order": 1
}
```

### Get sections for a project

#### Request Body
- **action** (string) - Required - "get"
- **project_id** (string) - Required - The ID of the project.

### Request Example
```json
{
  "action": "get",
  "project_id": "2203306141"
}
```

### Update section name

#### Request Body
- **action** (string) - Required - "update"
- **section_id** (string) - Required - The ID of the section to update.
- **name** (string) - Required - The new name for the section.

### Request Example
```json
{
  "action": "update",
  "section_id": "123456789",
  "name": "Currently Working"
}
```

### Reorder sections

#### Request Body
- **action** (string) - Required - "reorder"
- **project_id** (string) - Required - The ID of the project.
- **sections** (array) - Required - An array of section objects with their new order.
  - **id** (string) - Required - The ID of the section.
  - **section_order** (integer) - Required - The new order of the section.

### Request Example
```json
{
  "action": "reorder",
  "project_id": "2203306141",
  "sections": [
    {"id": "123", "section_order": 1},
    {"id": "456", "section_order": 2},
    {"id": "789", "section_order": 3}
  ]
}
```

### Move section to another project

#### Request Body
- **action** (string) - Required - "move"
- **section_id** (string) - Required - The ID of the section to move.
- **project_id** (string) - Required - The ID of the target project.

### Request Example
```json
{
  "action": "move",
  "section_id": "123456789",
  "project_id": "2203306142"
}
```

### Archive section

#### Request Body
- **action** (string) - Required - "archive"
- **section_name** (string) - Required - The name of the section to archive.

### Request Example
```json
{
  "action": "archive",
  "section_name": "Completed Tasks"
}
```
```

--------------------------------

### List Todoist Backups

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Retrieve a list of available backup versions for your Todoist account. Requires Pro/Business subscription.

```json
{"action": "list"}
```

--------------------------------

### Create a Section

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Create a new section within a project. Requires the project ID, section name, and an order number.

```json
{
  "action": "create",
  "project_id": "2203306141",
  "name": "In Progress",
  "order": 1
}
```

--------------------------------

### Testing and Validation Commands

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Perform various tests on the Todoist connection and features, including basic read-only tests, full CRUD testing with cleanup, performance benchmarking, and general tool validation.

```bash
"Test my Todoist connection"
```

```bash
"Run basic tests on all Todoist features" // Default: read-only API tests
```

```bash
"Run enhanced tests on all Todoist features" // Full CRUD testing with cleanup
```

```bash
"Benchmark Todoist API performance with 10 iterations"
```

```bash
"Validate that all MCP tools are working correctly"
```

--------------------------------

### Get Task Hierarchy

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieve the hierarchical structure of tasks, including subtasks, with an option to include completed tasks. Specify the root task ID for the hierarchy.

```json
{
  "action": "hierarchy",
  "task_id": "7025693456",
  "include_completed": true
}
```

--------------------------------

### Get Todoist Completed Tasks

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Retrieve a history of completed tasks. Filters can be applied by project ID, date range (since/until), and a limit for the number of tasks returned.

```json
{"action": "get", "project_id": "123", "limit": 50}
```

```json
{"action": "get", "since": "2024-01-01", "until": "2024-01-31"}
```

--------------------------------

### Quick Add Natural Language Parsing

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Use natural language to add tasks with due dates, projects, labels, assignees, priorities, deadlines, and descriptions. Supports multiple features in a single command.

```bash
"Quick add: Buy groceries tomorrow #Shopping @errands p1"
```

```bash
"Quick add: Review PR next Monday #Work @code-review p2 //Check error handling"
```

```bash
"Quick add: Call mom {deadline in 3 days}"
```

```bash
"Quick add: Team meeting today at 2pm #Work @meetings with reminder 1 hour before"
```

--------------------------------

### Task Discovery Commands

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Discover tasks by showing all tasks, listing high priority tasks due within a specific timeframe, or retrieving tasks within a particular project.

```bash
"Show all my tasks"
```

```bash
"List high priority tasks due this week"
```

```bash
"Get tasks in project 12345"
```

--------------------------------

### Get Todoist Tasks with Filters

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieve Todoist tasks based on specified filters, such as date and priority, within a particular project. A limit can be set for the number of results.

```json
{
  "action": "get",
  "filter": "today & p1",
  "project_id": "2203306141",
  "limit": 10
}
```

--------------------------------

### Invite User to Todoist Project

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Invite a user to a specific project by providing the `project_id` and the user's `email`. This action is part of collaboration management.

```json
{"action": "invite", "project_id": "123", "email": "user@example.com"}
```

--------------------------------

### todoist_utility - Testing and Utilities

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Provides utilities for testing API connections, running feature tests, benchmarking performance, finding, and merging duplicate tasks.

```APIDOC
## POST /utilities/test_connection

### Description
Tests the API connection.

### Method
POST

### Endpoint
/utilities/test_connection

### Parameters
#### Request Body
- **action** (string) - Required - Must be "test_connection"

### Request Example
```json
{
  "action": "test_connection"
}
```

## POST /utilities/test_features

### Description
Runs feature tests. Use 'basic' for read-only tests or 'enhanced' for full CRUD tests.

### Method
POST

### Endpoint
/utilities/test_features

### Parameters
#### Request Body
- **action** (string) - Required - Must be "test_features"
- **mode** (string) - Required - The test mode: "basic" or "enhanced"

### Request Example
```json
{
  "action": "test_features",
  "mode": "enhanced"
}
```

## POST /utilities/test_performance

### Description
Benchmarks the API performance.

### Method
POST

### Endpoint
/utilities/test_performance

### Parameters
#### Request Body
- **action** (string) - Required - Must be "test_performance"
- **iterations** (integer) - Required - The number of iterations to run for the benchmark

### Request Example
```json
{
  "action": "test_performance",
  "iterations": 10
}
```

## POST /utilities/find_duplicates

### Description
Finds duplicate tasks based on a similarity threshold.

### Method
POST

### Endpoint
/utilities/find_duplicates

### Parameters
#### Request Body
- **action** (string) - Required - Must be "find_duplicates"
- **threshold** (integer) - Required - The similarity threshold (0-100) for detecting duplicates
- **project_id** (string) - Optional - The ID of the project to search within

### Request Example
```json
{
  "action": "find_duplicates",
  "threshold": 80,
  "project_id": "2203306141"
}
```

## POST /utilities/merge_duplicates

### Description
Merges duplicate tasks.

### Method
POST

### Endpoint
/utilities/merge_duplicates

### Parameters
#### Request Body
- **action** (string) - Required - Must be "merge_duplicates"
- **keep_task_id** (string) - Required - The ID of the task to keep
- **duplicate_task_ids** (array of strings) - Required - An array of IDs of the duplicate tasks to merge
- **merge_action** (string) - Required - The action to perform on the duplicates (e.g., "complete")

### Request Example
```json
{
  "action": "merge_duplicates",
  "keep_task_id": "7025693456",
  "duplicate_task_ids": ["7025693457", "7025693458"],
  "merge_action": "complete"
}
```
```

--------------------------------

### Create and Get Todoist Comments

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Use these JSON payloads to create or retrieve comments associated with Todoist tasks or projects. Ensure you provide either a `task_id` or `project_id` for these actions.

```json
{"action": "create", "task_id": "123", "content": "Great progress!"}
```

```json
{"action": "get", "task_id": "123"}
```

--------------------------------

### Download Todoist Backup

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Download a specific backup version of your Todoist data. Requires Pro/Business subscription and the version identifier.

```json
{"action": "download", "version": "2024-01-15_12-00"}
```

--------------------------------

### List workspaces

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieves a list of available workspaces. This action is specific to the Business plan.

```json
{
  "action": "workspaces"
}
```

--------------------------------

### Quick Add Task Handler

Source: https://github.com/greirson/mcp-todoist/blob/main/CLAUDE.md

Handles natural language task creation using the Todoist Quick Add API. Located in `src/handlers/task-handlers.ts`.

```typescript
handleQuickAddTask
```

--------------------------------

### Get Archived Projects - Advanced Project Operations

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieve a list of all archived projects. This action is useful for accessing projects that are no longer actively used but may contain historical data.

```json
// Get archived projects
{
  "action": "get_archived"
}
```

--------------------------------

### Create a Todoist Task

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Use this to create a new task with full attribute support. Specify content, due date, and priority.

```json
{"action": "create", "content": "Buy groceries", "due_string": "tomorrow", "priority": 1}
```

--------------------------------

### Manual JSON Configuration for Todoist MCP Server

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Integrate the Todoist MCP server into your MCP client's configuration file by adding this JSON object. Ensure you replace 'your_api_token_here' with your actual Todoist API token.

```json
{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}
```

--------------------------------

### Download a specific backup

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Downloads a specific backup file identified by its version string. Requires Pro or Business plan.

```json
{
  "action": "download",
  "version": "2024-01-15_12-00"
}
```

--------------------------------

### Label Management Commands

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Manage labels by showing all labels, creating new labels with color, updating existing labels, and deleting unused labels.

```bash
"Show me all my labels"
```

```bash
"Create a new label called 'Urgent' with red color"
```

```bash
"Update the 'Work' label to be blue and mark as favorite"
```

```bash
"Delete the unused 'Old Project' label"
```

```bash
"Get usage statistics for all my labels"
```

--------------------------------

### Create a Label

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Create a new label with a specified name, color, and favorite status. Labels are used for categorizing tasks.

```json
{
  "action": "create",
  "name": "urgent",
  "color": "red",
  "is_favorite": true
}
```

--------------------------------

### Quick Add Todoist Task

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Create a task using natural language input. Supports due dates, projects, labels, and priorities.

```json
{"action": "quick_add", "text": "Meeting tomorrow at 2pm #Work @urgent p1"}
```

--------------------------------

### Create a new Todoist section

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Create a new section within a specified project. Requires project ID and section name.

```json
{"action": "create", "project_id": "123", "name": "In Progress"}
```

--------------------------------

### Create and Update Todoist Filters

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Manage custom filters by creating new ones with a name and query, or updating existing filters using their ID or name. Requires a Pro/Business plan.

```json
{"action": "create", "name": "Urgent Today", "query": "today & p1"}
```

```json
{"action": "update", "filter_id": "123", "query": "p1 | p2"}
```

--------------------------------

### Create Todoist Project Note

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Create a new note associated with a specific project. Requires the project ID and the content of the note.

```json
{"action": "create", "project_id": "123", "content": "Project kickoff notes..."}
```

--------------------------------

### Move Todoist Project to Parent

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Use this action to move a project to become a sub-project under another parent project. Requires both project IDs.

```json
{"action": "move_to_parent", "project_id": "123", "parent_id": "456"}
```

--------------------------------

### Accept an invitation

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Accepts a pending invitation using the invitation ID and a secret key. This action joins the user to a project or workspace.

```json
{
  "action": "accept",
  "invitation_id": "inv_123",
  "secret": "abc123"
}
```

--------------------------------

### todoist_backup - Backup Management

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Manages Todoist automatic backups, allowing listing and downloading of backup versions. Requires Pro or Business plan.

```APIDOC
## GET /backups/list

### Description
Lists all available automatic backup versions.

### Method
GET

### Endpoint
/backups/list

### Parameters
#### Request Body
- **action** (string) - Required - Must be "list"

### Request Example
```json
{
  "action": "list"
}
```

## POST /backups/download

### Description
Downloads a specific backup version.

### Method
POST

### Endpoint
/backups/download

### Parameters
#### Request Body
- **action** (string) - Required - Must be "download"
- **version** (string) - Required - The version string of the backup to download (e.g., "2024-01-15_12-00")

### Request Example
```json
{
  "action": "download",
  "version": "2024-01-15_12-00"
}
```
```

--------------------------------

### Subtask Management Commands

Source: https://github.com/greirson/mcp-todoist/blob/main/README.md

Manage subtasks by creating them under specific tasks, creating multiple subtasks at once, converting tasks to subtasks, promoting subtasks to main tasks, and viewing task hierarchies.

```bash
"Create subtask 'Prepare agenda' under task 'Team Meeting'"
```

```bash
"Create multiple subtasks for 'Launch Project': 'Design UI', 'Write tests', 'Deploy'"
```

```bash
"Convert task 'Code Review' to a subtask of 'Release v2.0'"
```

```bash
"Promote subtask 'Bug Fix' to a main task"
```

```bash
"Show me the task hierarchy for 'Launch Project' with completion tracking"
```

--------------------------------

### Quick Add Todoist Task with Natural Language

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Create a Todoist task using natural language input, which supports project, label, priority, and date assignments, as well as comments.

```json
{
  "action": "quick_add",
  "text": "Call client tomorrow at 3pm #Work @phone p2 //Discuss contract renewal"
}
```

--------------------------------

### New Project Management Tools

Source: https://github.com/greirson/mcp-todoist/blob/main/CLAUDE.md

Introduces new tools for managing Todoist projects, including update, delete, archive, and collaborator retrieval.

```typescript
todoist_project_update
```

```typescript
todoist_project_delete
```

```typescript
todoist_project_archive
```

```typescript
todoist_project_collaborators_get
```

--------------------------------

### Promote Subtask

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Promote a subtask to a main task within a specified project. This action requires the subtask's ID and the target project's ID.

```json
{
  "action": "promote",
  "task_id": "7025693458",
  "project_id": "2203306141"
}
```

--------------------------------

### Test API connection

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Verifies that the API connection is working correctly.

```json
{
  "action": "test_connection"
}
```

--------------------------------

### Todoist Client Factory with Dry-Run

Source: https://github.com/greirson/mcp-todoist/blob/main/CLAUDE.md

The `createTodoistClient()` function automatically handles dry-run wrapping.

```typescript
createTodoistClient()
```

--------------------------------

### Create a custom filter

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Use this to create a new custom filter with a specified name, query, color, and favorite status. Requires Pro or Business plan.

```json
{
  "action": "create",
  "name": "Urgent Today",
  "query": "today & p1",
  "color": "red",
  "is_favorite": true
}
```

--------------------------------

### Create a new Todoist label

Source: https://github.com/greirson/mcp-todoist/blob/main/TOOLS_REFERENCE.md

Create a new label for task organization. Specify the name and optionally a color.

```json
{"action": "create", "name": "urgent", "color": "red"}
```

--------------------------------

### Bulk Complete Todoist Tasks by Date Range

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Complete multiple Todoist tasks within a specified project that are due before a given date.

```json
{
  "action": "bulk_complete",
  "project_id": "2203306141",
  "due_before": "2024-01-01"
}
```

--------------------------------

### todoist_activity - Activity Audit Trail

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Retrieves activity logs for auditing and tracking workspace changes. Requires Pro or Business plan.

```APIDOC
## GET /activity/get

### Description
Retrieves activity entries based on object type and event type.

### Method
GET

### Endpoint
/activity/get

### Parameters
#### Request Body
- **action** (string) - Required - Must be "get"
- **object_type** (string) - Required - The type of object to filter activity by (e.g., "item")
- **event_type** (string) - Required - The type of event to filter activity by (e.g., "completed")
- **limit** (integer) - Optional - The maximum number of entries to retrieve

### Request Example
```json
{
  "action": "get",
  "object_type": "item",
  "event_type": "completed",
  "limit": 50
}
```

## GET /activity/by_project/{project_id}

### Description
Retrieves activity logs for a specific project.

### Method
GET

### Endpoint
/activity/by_project/{project_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project

#### Request Body
- **action** (string) - Required - Must be "by_project"
- **limit** (integer) - Optional - The maximum number of entries to retrieve

### Request Example
```json
{
  "action": "by_project",
  "project_id": "2203306141",
  "limit": 20
}
```

## GET /activity/by_date

### Description
Retrieves activity logs within a specified date range.

### Method
GET

### Endpoint
/activity/by_date

### Parameters
#### Request Body
- **action** (string) - Required - Must be "by_date"
- **since** (string) - Required - The start date of the range (YYYY-MM-DD)
- **until** (string) - Required - The end date of the range (YYYY-MM-DD)

### Request Example
```json
{
  "action": "by_date",
  "since": "2024-01-01",
  "until": "2024-01-31"
}
```
```

--------------------------------

### Bulk Create Multiple Todoist Tasks

Source: https://context7.com/greirson/mcp-todoist/llms.txt

Create multiple Todoist tasks simultaneously by providing an array of task objects, each with its own content and optional attributes.

```json
{
  "action": "bulk_create",
  "tasks": [
    {"content": "Design mockups", "priority": 1, "due_string": "tomorrow"},
    {"content": "Write documentation", "priority": 2},
    {"content": "Set up CI/CD", "due_string": "next week", "labels": ["devops"]}
  ]
}
```