Skip to main content
Glama

Todoist MCP Server

An MCP (Model Context Protocol) server that provides comprehensive task management through Todoist. This enables AI assistants like Claude to create, manage, and organize tasks using natural language.

Features

Tools (21 total)

Tool

Description

list_tasks

List tasks with filtering (by project, priority, due date, etc.)

get_task

Get detailed task info including comments and subtasks

create_task

Create tasks with natural language due dates

update_task

Update task content, due date, priority, labels

complete_task

Mark tasks complete (handles recurring)

uncomplete_task

Reopen completed tasks

delete_task

Permanently delete tasks

move_task

Move tasks between projects/sections

list_projects

List all projects

create_project

Create new projects

update_project

Update project name, color, view style

delete_project

Permanently delete projects

list_sections

List sections within projects

create_section

Create sections

update_section

Rename or collapse/expand sections

move_section

Move sections between projects

delete_section

Permanently delete sections

list_labels

List all labels

create_label

Create new labels

update_label

Update label name, color, order

delete_label

Permanently delete labels

add_comment

Add comments to tasks

get_productivity_stats

Get completion statistics

quick_add

Natural language task entry

Resources

Resource

Description

todoist://today

Today's tasks including overdue

todoist://upcoming

Tasks due in the next 7 days

todoist://overdue

All overdue tasks

todoist://projects

Project overview with task counts

todoist://labels

Labels and usage counts

Prompts

Prompt

Description

daily_planning

Morning planning workflow

weekly_review

GTD-style weekly review

quick_capture

Rapid multi-task capture

task_breakdown

Break large tasks into subtasks

Related MCP server: Todoist MCP Server

Setup

1. Get Your Todoist API Token

  1. Go to https://todoist.com/app/settings/integrations/developer

  2. Scroll to "API token"

  3. Copy your token

2. Install Dependencies

cd todoist-mcp
npm install

3. Build

npm run build

4. Add to Claude Code

claude mcp add --transport stdio todoist \
  --env TODOIST_API_TOKEN=your_token_here \
  -- node /path/to/todoist-mcp/dist/index.js

Or add manually to your Claude Code configuration:

{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": ["/path/to/todoist-mcp/dist/index.js"],
      "env": {
        "TODOIST_API_TOKEN": "your_token_here"
      }
    }
  }
}

5. Verify Connection

In Claude Code, type /mcp to check the server is connected.

Usage Examples

Create a Task

"Add a task to review the budget report by Friday"

The AI will use create_task with natural language due date parsing.

View Today's Tasks

"What do I need to do today?"

Uses the todoist://today resource or list_tasks with dueToday: true.

Daily Planning

"Let's do my daily planning"

Invokes the daily_planning prompt for a guided planning session.

Quick Capture

"Add these tasks: call dentist tomorrow, review PR by EOD, update docs"

Uses quick_add or create_task for natural language entry.

Initialize GTD Structure (One-Time Setup)

Run the setup script to create a GTD-inspired structure:

TODOIST_API_TOKEN=your_token npx tsx scripts/setup-gtd-structure.ts

This creates:

  • Projects: Work, Personal (with sub-projects), Recurring, Someday/Maybe, Reference

  • Labels: Context (@computer, @phone), Energy (@high-energy), Time (@5min, @deep-work), Status (@waiting-for)

Natural Language Due Dates

Todoist supports flexible date parsing:

Input

Result

today

Today

tomorrow

Tomorrow

tomorrow at 2pm

Tomorrow at 2:00 PM

next monday

Next Monday

in 3 days

3 days from now

jan 15

January 15

every day

Daily recurring

every monday at 9am

Weekly on Monday at 9 AM

every weekday

Monday through Friday

Priority Mapping

API Value

Display

Color

4

P1 (highest)

Red

3

P2

Orange

2

P3

Yellow

1

P4 (default)

None

Rate Limiting

The server implements rate limiting to stay within Todoist's API limits:

  • Limit: 450 requests per 15 minutes

  • Caching: Projects and labels are cached for 5 minutes

Development

Run in Development Mode

npm run dev

This runs TypeScript in watch mode.

Test with MCP Inspector

npm run inspect

Opens the MCP Inspector for testing tools and resources.

Project Structure

todoist-mcp/
├── src/
│   ├── index.ts           # Entry point
│   ├── types/             # TypeScript type definitions
│   ├── services/          # Todoist client, caching, rate limiting
│   ├── tools/             # MCP tool implementations
│   ├── resources/         # MCP resource implementations
│   └── prompts/           # MCP prompt implementations
├── dist/                  # Compiled output
├── package.json
└── tsconfig.json

Troubleshooting

"TODOIST_API_TOKEN environment variable is required"

Make sure you've set the token in your MCP configuration:

claude mcp add --env TODOIST_API_TOKEN=your_token ...

Rate Limit Errors

The server automatically handles rate limiting, but if you hit limits:

  • Wait 15 minutes for the window to reset

  • Check get_productivity_stats to see current rate limit usage

Tasks Not Appearing

  • Verify your API token is correct

  • Check that tasks aren't filtered out (completed, different project, etc.)

  • Use list_tasks without filters to see all tasks

Quick Add Project Assignment

The quick_add tool uses Todoist's natural language parser, which may not always parse project names with spaces correctly. For example, "Task #My Project" might not assign to the "My Project" project.

Workaround: Use create_task with explicit projectId for reliable project assignment, or use project names without spaces.

License

MIT

Available Tools

24 tools
add_commentC

Add a comment to a task

Inputs: taskId (required), content (required).

complete_taskA

Mark a task as complete. For recurring tasks, this completes the current occurrence.

Inputs: taskId (required).

create_labelC

Create a new label

Inputs: name (required), color, isFavorite.

create_projectC

Create a new project

Inputs: name (required), color, parentId, isFavorite, +1 more.

create_sectionC

Create a new section within a project

Inputs: projectId (required), name (required).

create_taskC

Create a new task with optional due date, priority, labels, and project

Inputs: content (required), description, projectId, sectionId, +8 more.

delete_labelA

Permanently delete a label (tasks will keep their other labels)

Inputs: labelId (required).

delete_projectB

Permanently delete a project and all its tasks

Inputs: projectId (required).

delete_sectionB

Permanently delete a section (tasks will be moved to project root)

Inputs: sectionId (required).

delete_taskC

Permanently delete a task

Inputs: taskId (required).

get_productivity_statsC

Get task completion statistics and productivity insights

Inputs: period.

get_taskB

Get detailed information about a specific task including comments and subtasks

Inputs: taskId (required), includeComments.

list_labelsB

List all labels in the Todoist account

Inputs: no named parameters.

list_projectsB

List all projects in the Todoist account

Inputs: no named parameters.

list_sectionsC

List sections within a project

Inputs: projectId.

list_tasksB

List tasks with optional filtering by project, label, priority, due date, or custom filter

Inputs: projectId, sectionId, priority, dueToday, +5 more.

move_sectionC

Move a section to a different project

Inputs: sectionId (required), projectId (required).

move_taskC

Move a task to a different project, section, or make it a subtask

Inputs: taskId (required), projectId, sectionId, parentId.

quick_addA

Quickly add a task using natural language. Todoist will parse dates, priorities, labels, and projects from the text.

Inputs: text (required).

uncomplete_taskC

Reopen a completed task

Inputs: taskId (required).

update_labelC

Update an existing label (name, color, favorite status, order)

Inputs: labelId (required), name, color, order, +1 more.

update_projectC

Update an existing project (name, color, favorite status, view style)

Inputs: projectId (required), name, color, isFavorite, +1 more.

update_sectionC

Update a section (rename or collapse/expand)

Inputs: sectionId (required), name, collapsed.

update_taskC

Update an existing task (content, due date, priority, labels, etc.)

Inputs: taskId (required), content, description, labels, +6 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 24 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose targeting specific resources (tasks, projects, labels, sections) and actions (create, get, list, update, delete, move, complete). No ambiguity exists; for example, create_task vs. quick_add are differentiated by input method, and move_task vs. update_task handle different aspects of task modification.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern (e.g., create_task, list_labels, update_project) with no deviations. The naming is uniform and predictable, making it easy for agents to understand and select tools based on their actions and targets.

    Tool Count3/5

    With 24 tools, the count is borderline high for a todo management server, potentially feeling heavy. While each tool serves a specific function, the number might overwhelm agents, as typical well-scoped servers have 3-15 tools. However, it's not extreme enough to score lower.

    Completeness5/5

    The tool set provides complete CRUD/lifecycle coverage for the Todoist domain, including tasks, projects, labels, and sections. It covers all essential operations from creation to deletion, with additional utilities like moving, commenting, and productivity stats, leaving no obvious gaps for agent workflows.

    Related MCP Connectors

    Related MCP Servers