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)

Tool	Description
`list_tasks`	List tasks with filtering (by project, priority, due date, etc.)
`get_task`	Get detailed task info including comments and subtasks
`create_task`	Create tasks with natural language due dates
`update_task`	Update task content, due date, priority, labels
`complete_task`	Mark tasks complete (handles recurring)
`uncomplete_task`	Reopen completed tasks
`delete_task`	Permanently delete tasks
`move_task`	Move tasks between projects/sections
`list_projects`	List all projects
`create_project`	Create new projects
`update_project`	Update project name, color, view style
`delete_project`	Permanently delete projects
`list_sections`	List sections within projects
`create_section`	Create sections
`update_section`	Rename or collapse/expand sections
`move_section`	Move sections between projects
`delete_section`	Permanently delete sections
`list_labels`	List all labels
`create_label`	Create new labels
`update_label`	Update label name, color, order
`delete_label`	Permanently delete labels
`add_comment`	Add comments to tasks
`get_productivity_stats`	Get completion statistics
`quick_add`	Natural language task entry

Resources

Resource	Description
`todoist://today`	Today's tasks including overdue
`todoist://upcoming`	Tasks due in the next 7 days
`todoist://overdue`	All overdue tasks
`todoist://projects`	Project overview with task counts
`todoist://labels`	Labels and usage counts

Prompts

Prompt	Description
`daily_planning`	Morning planning workflow
`weekly_review`	GTD-style weekly review
`quick_capture`	Rapid multi-task capture
`task_breakdown`	Break large tasks into subtasks

Setup

1. Get Your Todoist API Token

Go to https://todoist.com/app/settings/integrations/developer
Scroll to "API token"
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:

Input	Result
`today`	Today
`tomorrow`	Tomorrow
`tomorrow at 2pm`	Tomorrow at 2:00 PM
`next monday`	Next Monday
`in 3 days`	3 days from now
`jan 15`	January 15
`every day`	Daily recurring
`every monday at 9am`	Weekly on Monday at 9 AM
`every weekday`	Monday through Friday

Priority Mapping

API Value	Display	Color
`4`	P1 (highest)	Red
`3`	P2	Orange
`2`	P3	Yellow
`1`	P4 (default)	None

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