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

Projects

Sections

Labels

Comments

Completed tasks (Pro)

Reminders (Pro)

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:

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