Todoist MCP Server
A Model Context Protocol (MCP) server that integrates Todoist task management with Claude. Manage your Todoist tasks conversationally without context-switching!
Features
- Get Tasks: Fetch and filter tasks by project, label, or custom filters
- Create Tasks: Add new tasks with priorities, due dates, and labels
- Update Tasks: Modify existing tasks, change priorities, defer dates
- Complete Tasks: Mark tasks as done
- List Projects: View all your Todoist projects
- List Labels: View all your Todoist labels
Perfect for:
- Managing tasks during high-stress work periods
- Bulk task operations (defer, prioritize, organize)
- Quick task triage without leaving your conversation with Claude
- ADHD-friendly task management with conversational interface
Prerequisites
- Python 3.10 or higher
- A Todoist account
- Todoist API token (get it here)
Installation
1. Clone the repository```bash
git clone https://github.com/yourusername/todoist-mcp-server.git
cd todoist-mcp-server
### 2. Create a virtual environment (recommended)```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
3. Install the package```bash
pip install -e .
### 4. Configure your API token
Create a `.env` file in the project root:```bash
cp .env.example .env
Edit .env and add your Todoist API token:```
TODOIST_API_TOKEN=your_actual_token_here
Get your token from: https://todoist.com/app/settings/integrations/developer
## Configuration for Claude Code
### Option 1: Configure in Claude Desktop (Recommended)
Add this to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json````json
{
"mcpServers": {
"todoist": {
"command": "python",
"args": ["-m", "todoist_mcp.server"],
"env": {
"TODOIST_API_TOKEN": "your_token_here"
}
}
}
}
Option 2: Use with Claude Code CLI
If using with claude-code CLI:```bash
Set environment variable
export TODOIST_API_TOKEN=your_token_here
Run the server
python -m todoist_mcp.server
Or configure in your MCP settings file for Claude Code.
### Restart Claude
After configuration, restart Claude Desktop or Claude Code to load the MCP server.
## Usage Examples
Once configured, you can interact with Todoist through natural conversation with Claude:
### View Today's Tasks```
You: "Show me my tasks for today"
Claude will use todoist_get_tasks with filter="today"
Create a Task```
You: "Create a task to review the infrastructure PR, priority 4, due tomorrow"
Claude will use todoist_create_task with appropriate parameters
### Bulk Defer Tasks```
You: "I'm overwhelmed. Show me all my tasks for today, then defer everything
except priority 4 items to next week"
Claude will:
1. Use todoist_get_tasks to see today's tasks
2. Use todoist_update_task to defer non-urgent items
Organize by Project```
You: "Show me my projects, then move all high-priority tasks to the 'Sprint' project"
Claude will:
1. Use todoist_get_projects to list projects
2. Use todoist_update_task to move tasks
### Complete Tasks```
You: "I just finished the deployment. Mark that task as complete"
Claude will use todoist_complete_task
Available Tools
todoist_get_tasks
Fetch tasks with optional filters.
Parameters:
- project_id (optional): Filter by project ID
- label (optional): Filter by label name
- filter (optional): Todoist filter query (e.g., "today", "overdue", "priority 1")
todoist_create_task
Create a new task.
Parameters:
- content (required): Task title/content
- description (optional): Task description
- project_id (optional): Project to add task to
- priority (optional): 1-4 (4 is highest)
- due_string (optional): Human-readable due date ("tomorrow", "next Monday", etc.)
- labels (optional): Array of label names
todoist_update_task
Update an existing task.
Parameters:
- task_id (required): ID of task to update
- content (optional): New task content
- description (optional): New description
- priority (optional): New priority (1-4)
- due_string (optional): New due date
- labels (optional): New labels array (replaces existing)
todoist_complete_task
Mark a task as complete.
Parameters:
- task_id (required): ID of task to complete
todoist_get_projects
List all projects (no parameters required).
todoist_get_labels
List all labels (no parameters required).
Troubleshooting
"TODOIST_API_TOKEN not set" error
- Make sure you've created a
.envfile with your token - Or set the environment variable in your shell/Claude config
- Get your token from: https://todoist.com/app/settings/integrations/developer
Server not appearing in Claude
- Check that your
claude_desktop_config.jsonsyntax is correct - Restart Claude Desktop completely
- Check Claude's logs for MCP connection errors
API errors
- Verify your token is valid and hasn't expired
- Check your internet connection
- Some operations require Todoist Premium (like labels)
Development
Running tests```bash
pip install -e ".[dev]"
pytest
### Code formatting```bash
black src/
ruff check src/
Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
License
MIT License - see LICENSE file for details.
Acknowledgments
- Built with the Model Context Protocol
- Uses the Todoist API
- Created for better ADHD-friendly task management
Links
- MCP Documentation
- Todoist API Documentation
- Get Todoist API Token
Support
For issues and feature requests, please open an issue.
Testing
The project includes a comprehensive test suite to ensure reliability.
Running Tests```bash
Install test dependencies
pip install pytest pytest-asyncio
Run all tests
PYTHONPATH=src pytest tests/ -v
```
Test Coverage
The test suite includes:
- API Method Validation: Ensures we're calling valid Todoist API methods (would have caught the
close_taskvscomplete_taskbug) - Handler Function Tests: Unit tests for all MCP handlers with mocked API calls
- Error Handling Tests: Validates proper error handling and user-friendly messages
See tests/README.md for more details.
