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

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