# 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
```bash
cd todoist-mcp
npm install
```
### 3. Build
```bash
npm run build
```
### 4. Add to Claude Code
```bash
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:
```json
{
"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:
```bash
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
```bash
npm run dev
```
This runs TypeScript in watch mode.
### Test with MCP Inspector
```bash
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:
```bash
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
