Todoist MCP Server

How to use

Use an MCP client to connect to the Todoist MCP Server and start managing your Todoist workspace with everyday language. You can create, update, read, and organize tasks, subtasks, projects, sections, labels, and reminders. You can also run dry-run sessions to validate actions before applying them to real data.

How to install

Prerequisites: Node.js (recommended LTS) and an active Todoist account. You will also need access to your Claude Desktop configuration.

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

Additional setup guidance

To start using the server, configure Claude Desktop with the MCP server entry shown above, replacing your_api_token_here with your actual Todoist API token. Then restart Claude Desktop and ask Claude to show your Todoist projects to verify the connection.

Dry-run mode

Dry-run mode lets you test operations without applying changes to your Todoist workspace. Enable it by adding the DRYRUN environment variable in the server configuration.

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

Tools overview

The server exposes a comprehensive set of tools to manage tasks, subtasks, projects, sections, labels, reminders, and more. Each tool supports CRUD operations, bulk actions, and querying capabilities to fit natural-language workflows.

Getting started workflow

1. Obtain your Todoist API token from Todoist settings under Integrations. 2. Add the MCP server configuration to Claude Desktop. 3. Restart Claude Desktop. 4. Ask Claude to show your Todoist projects to verify the connection.

Best practices

Start simple: begin with viewing projects, then create a task. Use natural language to engage with the system. Try dry-run for complex bulk operations. Leverage bulk tools to manage many tasks efficiently. Organize first by setting up projects and sections before creating large task lists.

Troubleshooting

No Todoist projects found or connection errors: verify your API token is correct and properly set in your Claude Desktop config. MCP server not loading: ensure the MCP package is installed and Claude Desktop is fully restarted. Check file paths and permissions for your operating system, and create missing config directories if required.

Notes on development and testing

The server offers tools for testing connections, validating features, and performing performance benchmarks. Use the provided commands to run tests, watch for changes, and check formatting and linting as part of your development workflow.

Examples of common usage

Project discovery and creation: ask to list projects or create a new project. Task management: ask to create, update, or complete tasks. Subtasks, sections, and labels: organize work with hierarchical structures and metadata. Reminders and comments: add reminders and discuss tasks with teammates.

Security and access

Treat your API token like a secret: store it securely and rotate it if you suspect it’s compromised. Grant minimal necessary permissions and monitor usage to protect your Todoist data.

Notes on configuration and runtime

Configure the MCP server entry in Claude Desktop to point to the Todoist MCP package. The runtime environment should include the Todoist API token and any optional flags such as DRYRUN for safe testing.

Development

If you are extending or contributing to the MCP server, ensure you compile and test changes locally. Validate inputs with robust type checks and keep the runtime behavior predictable for end users.

Changelog and support

For updates and issue reporting, follow the standard contribution process and open issues with clear reproduction steps. Support channels are typically the project’s issue tracker and community forums.

todoist_task

Manage individual tasks with create, get, update, delete, complete, reopen, and quick_add actions

todoist_task_bulk

Perform bulk create, update, delete, and complete operations across multiple tasks

todoist_subtask

Handle subtasks with create, bulk_create, convert, promote, and hierarchy features

todoist_project

Manage projects with create, get, update, delete, archive, and collaborators

todoist_project_ops

Advanced project operations like reorder and move_to_parent

todoist_section

Manage sections within projects with create, get, update, delete, move, reorder, archive

todoist_label

Manage labels including create, get, update, delete, and statistics

todoist_comment

Create, get, update, and delete comments on tasks or projects

todoist_reminder

Manage reminders (Pro/Business) for tasks

todoist_filter

Create, get, update, and delete custom filters (Pro)

todoist_collaboration

Handle invitations, notifications, and workspace operations for team collaboration

todoist_user

Access user info and productivity stats

todoist_utility

Testing and utility endpoints for connectivity and performance checks

todoist_activity

Retrieve logs, events, and summaries for activity auditing

todoist_task_ops

Advanced task operations like move, reorder, and close

todoist_completed

Retrieve completed tasks and related stats

todoist_backup

List and download automatic backups of Todoist data

todoist_notes

Create, get, update, and delete project notes