Todoist MCP — Cloudflare Worker

A Model Context Protocol (MCP) server for Todoist, hosted on Cloudflare Workers. Lets any AI assistant (Claude, GPT, Gemini, etc.) read and manage your Todoist tasks.

Built against the Todoist unified API v1 (https://api.todoist.com/api/v1). The older REST v2 / Sync v9 APIs are deprecated.

How it works

Telegram message
      ↓
  Your bot
      ↓
  LLM (Claude / GPT / Gemini / etc.)
      ↓  calls tools via MCP JSON-RPC
  This Worker  ←→  Todoist API

The Worker exposes a single POST / endpoint that speaks MCP JSON-RPC. Your bot connects to it and the LLM can call any of the 6 tools to read/write tasks.

Related MCP server: Todoist MCP Server

Your data model

You use Todoist's task/subtask hierarchy to simulate projects:

This matters for the AI: when you say "add a task to my Telegram bot project", the AI should find the parent task ID first, then call add_task with that parent_id.

Tools

Priority values

• 1 = Normal (default)

• 2 = Medium

• 3 = High

• 4 = Urgent

Filtering

The filter parameter accepts Todoist filter query syntax (e.g. "today", "overdue", "@work & p1"). When set, it takes precedence over mode/parent_id/label and returns a flat list.

Setup

1. Install dependencies

npm install

2. Set your secrets

Get your Todoist token from todoist.com/app/settings/integrations/developer.

# Your Todoist API token
npx wrangler secret put TODOIST_API_TOKEN

# A shared secret your bot sends to authenticate to this Worker.
# Generate a long random string, e.g.:  openssl rand -hex 32
npx wrangler secret put MCP_SECRET

Why MCP_SECRET? The Worker is on the public internet. Without this gate, anyone who finds the URL could read, edit, and delete your entire Todoist. Your bot must send it as Authorization: Bearer <MCP_SECRET> on every request.

3. Deploy

npm run deploy

Your endpoint: https://todoist-mcp.<your-subdomain>.workers.dev

Local development

# Put both secrets in .dev.vars (already gitignored):
# TODOIST_API_TOKEN=your_token_here
# MCP_SECRET=pick_a_long_random_string_here

npm run dev
# → http://localhost:8787

Connecting to your AI

See ai-system-prompt.md for the system prompt block to add to your Telegram bot so the AI knows how to use these tools correctly.

How to call a tool (raw JSON-RPC)

Every request needs the Authorization: Bearer <MCP_SECRET> header.

POST https://todoist-mcp.<your-subdomain>.workers.dev
Authorization: Bearer <your MCP_SECRET>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_task",
    "arguments": {
      "content": "Set up todoist MCP",
      "parent_id": "12345678",
      "due_string": "tomorrow",
      "priority": 3
    }
  }
}

Discover available tools

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }