todoist-mcp-server

A custom Node.js Model Context Protocol (MCP) server that connects Claude to Todoist using a permanent API token. No OAuth, no re-authentication, works identically on Claude web, Claude Code, and Claude mobile.

Why this exists

The problem

Todoist needs to work across three Claude surfaces:

• Claude web (claude.ai) on PC

• Claude Code on PC and Linux

• Claude mobile on iPhone

Every existing solution fails at least one of these. The core issue is authentication. Todoist's official MCP server (ai.todoist.net/mcp) uses OAuth, but Todoist does not issue OAuth refresh tokens. When the access token expires, Claude cannot silently refresh it and forces manual re-authentication. On Claude mobile this is impossible to fix: you cannot re-authenticate from the iOS app. This is a confirmed bug tracked in the Claude Code issue tracker: #5706, #12447, #19456, #28256.

What we evaluated

Why a custom server works

Todoist issues a permanent API token (Settings > Integrations > Developer). This token never expires unless manually revoked. It is not an OAuth token and requires no refresh.

A custom MCP server that authenticates to Todoist using this token (stored as an Azure environment variable, never in code) gives a hosted remote MCP URL that:

• Never requires re-authentication on any surface

• Works on Claude web, Claude Code, and Claude mobile identically

• Has no rate limits from a middleware layer

• Is fully under the owner's control

• Updates by editing one file in GitHub (Azure redeploys automatically)

API version note

Todoist REST API v2 and Sync API v9 are deprecated as of early 2026. This server uses the unified Todoist API v1 at https://api.todoist.com/api/v1.

Architecture

flowchart TD
    A["🖥️ Claude web (claude.ai)"] --> D
    B["💻 Claude Code (PC / Linux)"] --> D
    C["📱 Claude mobile (iOS)"] --> D

    D["todoist-mcp-server\nNode.js · Azure App Service"]

    D -->|"Todoist API v1\npermanent Bearer token, never expires"| E["api.todoist.com"]

    style D fill:#0078d4,color:#fff,stroke:none
    style E fill:#db4035,color:#fff,stroke:none

Key design decisions:

• Stateless HTTP transport: StreamableHTTPServerTransport with no session ID generator. Each request is self-contained. Safe on any platform that recycles processes (Azure App Service, Cloud Run, etc.).

• Native fetch: Node 20+ has built-in fetch. No axios, no node-fetch at runtime.

• X-Request-Id on mutations: Todoist uses this for idempotency on POST/DELETE. Generated per request with crypto.randomUUID().

• Tool-per-operation: Each API endpoint is its own MCP tool with typed Zod parameters. Gives Claude precise descriptions and significantly improves how reliably it picks the right tool.

• No Express: Node's built-in http module keeps dependencies minimal and startup fast.

Tools (33 total)

Tasks (8)

Priority scale: 4 = urgent (red), 3 = high (orange), 2 = medium (blue), 1 = normal.

Projects (5)

Sections (5)

Labels (5)

Comments (5)

Reminders (4)

Requires Todoist Pro. Reminders fire a notification at a specific time or relative to a task's due date.

Productivity stats (1)

Adding to Claude

claude.ai (web and mobile)

1. Go to claude.ai and sign in.

2. Click your profile icon, then Customize.

3. Go to Connectors and click +.

4. Select Add custom connector and fill in:

   • Name: Todoist

   • Remote MCP server URL: https://your-deployed-app-url/mcp

   • Leave all OAuth fields blank.

5. Click Add.

Syncs automatically to the Claude mobile app and Claude Code. No re-authentication ever.

Claude Code (.mcp.json)

{
  "mcpServers": {
    "todoist": {
      "type": "http",
      "url": "https://your-deployed-app-url/mcp"
    }
  }
}

Local development

npm install
export TODOIST_API_TOKEN=your_token_here
npm start

Health check: http://localhost:8080/health MCP endpoint: http://localhost:8080/mcp

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

A note

This server exists because I love both Claude and Todoist, and the broken OAuth re-authentication flow was ruining the experience of using them together. Hopefully this workaround becomes unnecessary someday. If Anthropic fixes Claude's MCP OAuth token refresh (#5706, #12447, #19456, #28256) or Todoist issues proper refresh tokens, the official MCP server at ai.todoist.net/mcp would make this redundant. Until then, this works.

License

MIT. Copyright (c) 2026 Shashank Vadrevu. See LICENSE.