Skip to main content
Glama

todoist-v1-mcp-server

A clean, reliable MCP (Model Context Protocol) server for Todoist — built on the Todoist unified API v1.

Why this exists

The official Todoist web MCP (todoist-ai) has a known persistent disconnection bug on the Anthropic side that requires reconnecting daily. Community alternatives are either built on the deprecated REST API v2 or have schema validation bugs that cause failures when Todoist returns additional fields as their API evolves.

This server:

  • Targets the current Todoist API v1 (not deprecated v2)

  • Uses stdio transport — no cloud dependency, no daily reconnections

  • Uses the modern MCP SDK registerTool() API (not the deprecated setRequestHandler pattern)

  • Never enforces strict output schemas on API responses — Todoist can add new fields freely without breaking anything

  • Zero SDK wrapper dependency — direct HTTP calls via axios, so there's no intermediary library drifting from the API

Related MCP server: MCP Todoist

Tools (31 total)

Tasks

Tool

Description

todoist_get_tasks

List/filter tasks — supports Todoist filter strings like "today", "overdue", "p1", "#ProjectName", "7 days"

todoist_get_task

Get a single task by ID

todoist_create_task

Create a task with natural language due dates ("tomorrow", "every monday", etc.)

todoist_update_task

Update any field; pass clear_due_date: true to remove a due date

todoist_complete_task

Mark a task as done

todoist_reopen_task

Reopen a completed task

todoist_delete_task

Permanently delete a task

Projects

Tool

Description

todoist_get_projects

List all projects

todoist_get_project

Get a single project by ID

todoist_create_project

Create a project (with color, view style, parent)

todoist_update_project

Update a project

todoist_delete_project

Permanently delete a project and all its tasks

Sections

Tool

Description

todoist_get_sections

List sections within a project

todoist_create_section

Create a section

todoist_update_section

Rename a section

todoist_delete_section

Delete a section

Labels

Tool

Description

todoist_get_labels

List all personal labels

todoist_create_label

Create a label

todoist_update_label

Update a label

todoist_delete_label

Delete a label

Comments

Tool

Description

todoist_get_comments

List comments on a task or project (paginated)

todoist_get_comment

Get a single comment by ID

todoist_create_comment

Add a comment to a task or project (Markdown supported)

todoist_update_comment

Edit an existing comment's content

todoist_delete_comment

Permanently delete a comment

Completed tasks (Pro)

Tool

Description

todoist_get_completed_tasks

Query completed tasks by completion date (≤3mo) or due date (≤6wk). Pro-only.

Reminders (Pro)

Tool

Description

todoist_get_reminders

List reminders, optionally filtered by task_id. Pro-only.

todoist_get_reminder

Get a single reminder by ID. Pro-only.

todoist_create_reminder

Create a relative (minute_offset before due) or absolute reminder. Pro-only.

todoist_update_reminder

Update reminder timing or notification service. Pro-only.

todoist_delete_reminder

Permanently delete a reminder. Pro-only.

Pro-tier handling: Reminders and completed-task queries require a Todoist Pro subscription. If the API returns a Pro-gate error (HTTP 402, or 403 with a premium/pro/upgrade/paid/subscription keyword), the server returns a clean message explaining the feature requires Pro rather than leaking the raw API error.

Setup

1. Get your Todoist API token

Go to Todoist → Settings → Integrations → Developer and copy your API token.

2. Install and build

git clone https://github.com/christulino/todoist-v1-mcp-server
cd todoist-v1-mcp-server
npm install
npm run build

3. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop. You should see "todoist" in the connected MCP servers.

4. Configure Claude Code (optional)

claude mcp add todoist -- node /absolute/path/to/todoist-v1-mcp-server/dist/index.js

Then set the env var:

export TODOIST_API_TOKEN=your_api_token_here

Or add it to your shell profile.

Usage examples

Once connected, Claude can handle natural language like:

  • "What's on my plate today?" → uses todoist_get_tasks with filter: "today"

  • "Add a task to call the dentist next Tuesday" → uses todoist_create_task

  • "Mark the dentist task as done" → uses todoist_complete_task

  • "Show me everything overdue" → uses todoist_get_tasks with filter: "overdue"

  • "Create a project called Home Renovation" → uses todoist_create_project

  • "What projects do I have?" → uses todoist_get_projects

Todoist filter syntax

The filter parameter in todoist_get_tasks supports Todoist's full natural language filter syntax:

Filter

Meaning

today

Due today

overdue

Past due

7 days

Due in the next 7 days

p1

Priority urgent

#ProjectName

Tasks in a specific project

@labelname

Tasks with a specific label

no due date

Tasks without a due date

today | overdue

Today or overdue (combine with |)

today & @waiting

Today AND labeled 'waiting'

Full filter documentation: https://todoist.com/help/articles/introduction-to-filters

Requirements

  • Node.js 18+

  • A Todoist account (free tier works)

Development

npm run dev   # tsx watch mode with auto-reload
npm run build # compile TypeScript
npm start     # run compiled server

Testing

The test suite hits the live Todoist API and runs a full CRUD cycle across tasks, projects, sections, labels, comments, and reminders, plus a read-only smoke test for completed-task querying. Reminders and completed-task tests detect Pro-tier gating (HTTP 402/403) and report cleanly when the account is on the Free tier. All test data is prefixed with [mcp-test] and cleaned up automatically.

TODOIST_API_TOKEN=your_token npm test

Your API token is at Todoist → Settings → Integrations → Developer — same token you put in claude_desktop_config.json.

Contributing

PRs welcome. The goal is a minimal, correct implementation that stays current with the Todoist API v1. Priorities:

  1. Correctness over cleverness

  2. Permissive output handling (never reject unknown API fields)

  3. Helpful error messages that tell you what went wrong and how to fix it

License

MIT

Available Tools

20 tools
todoist_complete_taskComplete Todoist TaskA
Idempotent

Mark a Todoist task as completed (close it).

This is the standard way to check off a task. For recurring tasks, this advances to the next occurrence rather than permanently removing it.

Use todoist_delete_task to permanently remove a task instead.

Inputs: task_id (required).

todoist_create_labelCreate Todoist LabelA

Create a new personal label in Todoist.

Returns the created label's ID and name. Use the label name (not ID) when assigning labels to tasks with todoist_create_task or todoist_update_task.

Inputs: name (required), color, order, is_favorite.

todoist_create_projectCreate Todoist ProjectA

Create a new project in Todoist.

Color options: berry_red, red, orange, yellow, olive_green, lime_green, green, mint_green, teal, sky_blue, light_blue, blue, grape, violet, lavender, magenta, salmon, charcoal, grey, taupe.

Returns the full created project object including its assigned ID.

Inputs: name (required), parent_id, color, is_favorite, +1 more.

todoist_create_sectionCreate Todoist SectionA

Create a new section within a Todoist project.

Returns the created section's ID and details. Use the section ID when creating tasks (todoist_create_task) to add them directly to this section.

Inputs: name (required), project_id (required), order.

todoist_create_taskCreate Todoist TaskA

Create a new task in Todoist.

The due_string field supports natural language: "tomorrow", "every monday", "Feb 20", "next week", "in 3 hours", etc.

Priority levels: 1=normal (default), 2=medium, 3=high, 4=urgent.

Returns the full created task object including its assigned ID.

Inputs: content (required), description, project_id, section_id, +6 more.

todoist_delete_labelDelete Todoist LabelA
Destructive

Permanently delete a personal Todoist label.

The label will be removed from all tasks that currently use it. This cannot be undone.

Inputs: label_id (required).

todoist_delete_projectDelete Todoist ProjectA
Destructive

Permanently delete a Todoist project and all its tasks. This cannot be undone.

WARNING: All tasks within the project will also be deleted.

Inputs: project_id (required).

todoist_delete_sectionDelete Todoist SectionA
Destructive

Permanently delete a Todoist section.

Tasks within the section are NOT deleted — they are moved to the parent project (unsectioned). The section itself is permanently removed and cannot be undone.

Inputs: section_id (required).

todoist_delete_taskDelete Todoist TaskA
Destructive

Permanently delete a Todoist task. This action cannot be undone.

For recurring tasks or tasks you just want to mark as done, use todoist_complete_task instead.

Inputs: task_id (required).

todoist_get_labelsGet Todoist LabelsA
Read-onlyIdempotent

List all personal labels in the user's Todoist account.

Returns label IDs, names, colors, and sort order. Use label names (not IDs) when creating or updating tasks.

Inputs: response_format.

todoist_get_projectGet Todoist ProjectA
Read-onlyIdempotent

Retrieve a single Todoist project by its ID.

Returns full project details including name, color, parent project, comment count, sharing status, and view style.

Inputs: project_id (required), response_format.

todoist_get_projectsGet Todoist ProjectsA
Read-onlyIdempotent

List all projects in the user's Todoist account.

Returns project IDs, names, colors, hierarchy (parent_id for sub-projects), and metadata like whether each project is a favorite or shared.

Use project IDs with todoist_get_tasks to fetch tasks for a specific project.

Inputs: response_format.

todoist_get_sectionsGet Todoist SectionsA
Read-onlyIdempotent

List all sections within a Todoist project.

Sections are used to organize tasks within a project into groups. Returns section IDs, names, and sort order.

Use section IDs with todoist_get_tasks (section_id param) or todoist_create_task (section_id param) to work with tasks in specific sections.

Inputs: project_id (required), response_format.

todoist_get_taskGet Todoist TaskA
Read-onlyIdempotent

Retrieve a single Todoist task by its ID.

Returns full task details: content, description, due date, priority, labels, project/section IDs, comment count, and creation timestamp.

Inputs: task_id (required), response_format.

todoist_get_tasksGet Todoist TasksA
Read-onlyIdempotent

List and filter tasks from Todoist.

Use the filter parameter for powerful natural-language Todoist filters:

  • "today" → tasks due today

  • "overdue" → past-due tasks

  • "7 days" → due in the next 7 days

  • "p1" → priority 1 (urgent)

  • "#Work" → tasks in project named Work

  • "@waiting" → tasks with label 'waiting'

  • "no due date" → tasks with no due date

  • Combine with & (AND), | (OR): "today | overdue"

Alternatively, filter by project_id, section_id, or label directly.

Returns task IDs, content, due dates, priorities, labels, and project/section IDs.

Inputs: filter, project_id, section_id, label, +3 more.

todoist_reopen_taskReopen Todoist TaskA
Idempotent

Reopen (uncomplete) a previously completed Todoist task.

Useful for tasks that were marked done by mistake or need to be revisited.

Inputs: task_id (required).

todoist_update_labelUpdate Todoist LabelA
Idempotent

Update an existing Todoist label. Only include fields to change.

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

todoist_update_projectUpdate Todoist ProjectA
Idempotent

Update an existing Todoist project. Only include fields to change.

Inputs: project_id (required), name, color, is_favorite, +1 more.

todoist_update_sectionUpdate Todoist SectionB
Idempotent

Rename an existing Todoist section.

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

todoist_update_taskUpdate Todoist TaskA
Idempotent

Update an existing Todoist task.

Only include the fields you want to change — all fields are optional. To clear a due date, pass clear_due_date: true (sends due_string: "no date" — empty string is silently ignored and due: null returns 400). To remove all labels, pass labels as an empty array [].

Priority: 1=normal, 2=medium, 3=high, 4=urgent.

Inputs: task_id (required), content, description, clear_due_date, +6 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting specific resources (tasks, projects, labels, sections) and actions (create, get, update, delete, complete, reopen). Descriptions explicitly differentiate similar tools (e.g., todoist_complete_task vs. todoist_delete_task), eliminating ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with the prefix 'todoist_' (e.g., todoist_create_task, todoist_get_labels). The naming is uniform across all 20 tools, using snake_case and clear action verbs aligned with CRUD operations.

    Tool Count5/5

    With 20 tools, the server provides comprehensive coverage for Todoist's domain, including tasks, projects, labels, and sections. Each tool serves a distinct, necessary function, and the count is well-scoped for managing a task management system without being excessive.

    Completeness5/5

    The tool set offers complete CRUD/lifecycle coverage for all core resources (tasks, projects, labels, sections), including specialized actions like complete, reopen, and filtering. There are no obvious gaps; agents can perform all essential operations without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers