# Todoist MCP Server
MCP server for Todoist task management. Provides 12 tools for tasks, projects, and labels.
## Features
- **Tasks**: Create, list, update, complete, reopen, and delete tasks
- **Projects**: List and create projects, including sub-projects
- **Labels**: List and create labels for task organization
- **Filters**: Support for Todoist filter syntax (`today`, `overdue`, `p1`, etc.)
- **Natural language dates**: Use `tomorrow`, `next Monday`, `every week`, etc.
## Installation
### Option 1: uvx (Recommended)
Zero-install method using [uv](https://docs.astral.sh/uv/). Add to `~/.claude.json`:
```json
{
"mcpServers": {
"todoist": {
"command": "uvx",
"args": ["--from", "git+https://github.com/IAMSamuelRodda/todoist-mcp", "todoist-mcp"],
"env": {
"TODOIST_API_TOKEN": "your-api-token"
}
}
}
}
```
### Option 2: Local Clone
```bash
mkdir -p ~/.claude/mcp-servers
git clone https://github.com/IAMSamuelRodda/todoist-mcp.git ~/.claude/mcp-servers/todoist-mcp
cd ~/.claude/mcp-servers/todoist-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
Add to `~/.claude.json`:
```json
{
"mcpServers": {
"todoist": {
"command": "~/.claude/mcp-servers/todoist-mcp/.venv/bin/python",
"args": ["~/.claude/mcp-servers/todoist-mcp/todoist_mcp.py"],
"env": {
"TODOIST_API_TOKEN": "your-api-token"
}
}
}
}
```
### Get Your API Token
1. Open Todoist (web or app)
2. Go to **Settings** → **Integrations** → **Developer**
3. Copy your **API token**
## Updating
### uvx users
```bash
uv cache clean todoist-mcp
```
### Local clone users
```bash
cd ~/.claude/mcp-servers/todoist-mcp
git pull
source .venv/bin/activate
pip install -r requirements.txt
```
## Available Tools
| Tool | Description |
|------|-------------|
| `todoist_list_projects` | List all projects |
| `todoist_get_project` | Get project details |
| `todoist_create_project` | Create a new project |
| `todoist_list_tasks` | List tasks with filters |
| `todoist_get_task` | Get task details |
| `todoist_create_task` | Create a new task |
| `todoist_update_task` | Update a task |
| `todoist_complete_task` | Mark task complete |
| `todoist_reopen_task` | Reopen a completed task |
| `todoist_delete_task` | Delete a task |
| `todoist_list_labels` | List all labels |
| `todoist_create_label` | Create a new label |
## Usage Examples
Once configured, you can ask Claude:
- "Show me my tasks for today"
- "Create a task to review the quarterly report due next Friday"
- "List all my projects"
- "Mark task 123456789 as complete"
- "What are my overdue tasks?"
- "Create a high-priority task in my Work project"
## Filter Syntax
The `todoist_list_tasks` tool supports Todoist's filter syntax:
- `today` - Tasks due today
- `tomorrow` - Tasks due tomorrow
- `overdue` - Overdue tasks
- `p1`, `p2`, `p3`, `p4` - Filter by priority
- `no due date` - Tasks without due dates
- `7 days` - Tasks due in the next 7 days
- `@label_name` - Tasks with specific label
- `#project_name` - Tasks in specific project
## License
MIT
