Todoist MCP Server

An MCP (Model Context Protocol) server that provides comprehensive task management through Todoist. This enables AI assistants like Claude to create, manage, and organize tasks using natural language.

Features

Tools (21 total)

Resources

Prompts

Setup

1. Get Your Todoist API Token

1. Go to https://todoist.com/app/settings/integrations/developer

2. Scroll to "API token"

3. Copy your token

2. Install Dependencies

cd todoist-mcp
npm install

3. Build

npm run build

4. Add to Claude Code

claude mcp add --transport stdio todoist \
  --env TODOIST_API_TOKEN=your_token_here \
  -- node /path/to/todoist-mcp/dist/index.js

Or add manually to your Claude Code configuration:

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

5. Verify Connection

In Claude Code, type /mcp to check the server is connected.

Usage Examples

Create a Task

"Add a task to review the budget report by Friday"

The AI will use create_task with natural language due date parsing.

View Today's Tasks

"What do I need to do today?"

Uses the todoist://today resource or list_tasks with dueToday: true.

Daily Planning

"Let's do my daily planning"

Invokes the daily_planning prompt for a guided planning session.

Quick Capture

"Add these tasks: call dentist tomorrow, review PR by EOD, update docs"

Uses quick_add or create_task for natural language entry.

Initialize GTD Structure (One-Time Setup)

Run the setup script to create a GTD-inspired structure:

TODOIST_API_TOKEN=your_token npx tsx scripts/setup-gtd-structure.ts

This creates:

• Projects: Work, Personal (with sub-projects), Recurring, Someday/Maybe, Reference

• Labels: Context (@computer, @phone), Energy (@high-energy), Time (@5min, @deep-work), Status (@waiting-for)

Natural Language Due Dates

Todoist supports flexible date parsing:

Priority Mapping

Rate Limiting

The server implements rate limiting to stay within Todoist's API limits:

• Limit: 450 requests per 15 minutes

• Caching: Projects and labels are cached for 5 minutes

Development

Run in Development Mode

npm run dev

This runs TypeScript in watch mode.

Test with MCP Inspector

npm run inspect

Opens the MCP Inspector for testing tools and resources.

Project Structure

todoist-mcp/
├── src/
│   ├── index.ts           # Entry point
│   ├── types/             # TypeScript type definitions
│   ├── services/          # Todoist client, caching, rate limiting
│   ├── tools/             # MCP tool implementations
│   ├── resources/         # MCP resource implementations
│   └── prompts/           # MCP prompt implementations
├── dist/                  # Compiled output
├── package.json
└── tsconfig.json

Troubleshooting

"TODOIST_API_TOKEN environment variable is required"

Make sure you've set the token in your MCP configuration:

claude mcp add --env TODOIST_API_TOKEN=your_token ...

Rate Limit Errors

The server automatically handles rate limiting, but if you hit limits:

• Wait 15 minutes for the window to reset

• Check get_productivity_stats to see current rate limit usage

Tasks Not Appearing

• Verify your API token is correct

• Check that tasks aren't filtered out (completed, different project, etc.)

• Use list_tasks without filters to see all tasks

Quick Add Project Assignment

The quick_add tool uses Todoist's natural language parser, which may not always parse project names with spaces correctly. For example, "Task #My Project" might not assign to the "My Project" project.

Workaround: Use create_task with explicit projectId for reliable project assignment, or use project names without spaces.

License

MIT