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

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:

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