Todoist MCP Server

How to use

You interact with Todoist through an MCP client by adding Todoist as an MCP server. Once connected, your AI assistant can fetch project lists, create sections, add tasks, assign labels, and post comments based on natural language commands. You can perform bulk actions like moving multiple tasks between projects or sections, closing or reopening tasks, and organizing your workspace with labels and comments integrated into conversations.

How to install

Prerequisites: ensure Docker is installed on your machine. You also need a Todoist API token to authorize access to your Todoist data.

1. Obtain your Todoist API token from your Todoist developer settings.

2. Run the MCP server using Docker with your API token included in the environment. Use the following command as a starting point.

{
  "mcpServers": {
    "todoist": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TODOIST_API_TOKEN=<your_api_token_here>",
        "ghcr.io/koki-develop/todoist-mcp-server:latest"
      ]
    }
  }
}

Additional setup and usage notes

Configure your MCP client by adding the server configuration shown above. Replace <your_api_token_here> with your actual Todoist API token. The server will expose endpoints that allow your AI assistant to query and manipulate Todoist data according to the tools described in the server capabilities.

Security considerations

Keep your Todoist API token secret. Treat it like a password and do not share it in logs or insecure channels. Use secure storage for the token and restrict access to the MCP client configuration.

Troubleshooting

If you encounter connection issues, verify that Docker is running, the API token is correct, and the MCP client is configured to reach the Todoist MCP server. Check the container logs for authentication errors or missing permissions.

get_projects

Fetches all Todoist projects accessible to you, including metadata like name, color, and hierarchy.

get_project

Fetches detailed information for a single project by its ID, including configuration and structure.

create_project

Creates a new Todoist project with customizable settings.

update_project

Updates properties of an existing project.

delete_project

Permanently removes a project and all associated data.

get_sections

Retrieves all sections within a specific project with metadata such as name and order.

get_section

Fetches details for a specific section by its ID.

create_section

Creates a new section within a project.

update_section

Updates the name of an existing section.

delete_section

Removes a section and moves its tasks to the project root.

get_tasks

Retrieves tasks with flexible filtering and returns metadata like due dates and labels.

get_tasks_by_filter

Retrieves tasks using advanced Todoist filter syntax with automatic pagination.

get_task

Fetches detailed information for a specific task by its ID.

create_task

Creates a new Todoist task with comprehensive options.

update_task

Updates properties of an existing task.

delete_task

Permanently deletes a task and associated data.

close_task

Marks a task as completed, preserving data.

reopen_task

Reopens a completed task, restoring its active state.

move_tasks_to_project

Moves multiple tasks to another project.

move_tasks_to_section

Moves multiple tasks to a different section.

move_tasks_to_parent

Converts multiple tasks to subtasks under a specified parent.

create_label

Creates a new personal label with configurable properties.

update_label

Updates properties of an existing label.

get_label

Fetches details for a specific label by ID.

get_labels

Fetches all labels available to the user.

delete_label

Deletes a label and removes it from all tasks.

create_task_comment

Adds a comment to a task with optional attachments.

create_project_comment

Adds a comment to a project with optional attachments.

update_comment

Updates a comment's content while preserving metadata.

get_task_comments

Fetches all comments for a specific task.

get_project_comments

Fetches all comments for a specific project.

delete_comment

Deletes a specific comment by ID.