Todoist MCP Server

# Todoist MCP Server A comprehensive Model Context Protocol (MCP) server for Todoist that enables AI assistants to manage tasks, projects, labels, sections, and comments through natural conversation. ## Features The Todoist MCP server provides full task management capabilities: ### 📁 Project Management - **List Projects** - View all projects with hierarchy, colors, and metadata - **Create Projects** - Add new projects with customization options - **Update Projects** - Modify project properties like name, color, and view style ### ✅ Task Operations - **List Tasks** - View tasks with filters (by project, label, or Todoist filters) - **Create Tasks** - Add tasks with full control over properties - **Quick Add Tasks** - Use natural language to create tasks - **Update Tasks** - Modify task content, due dates, priorities, and labels - **Complete Tasks** - Mark tasks as done (handles recurring tasks automatically) ### 📑 Organization - **Sections** - List and create sections to organize tasks within projects - **Labels** - Manage personal labels for task categorization - **Comments** - Add and view comments on tasks and projects ## Installation ### Prerequisites - Python 3.9 or higher - A Todoist account with API access - Your Todoist API token (found in Settings → Integrations → Developer) ### Setup 1. **Install the MCP Python SDK and dependencies:** ```bash pip install mcp httpx pydantic ``` 2. **Save the server file:** Save `todoist_mcp.py` to a location on your system (e.g., `~/mcp-servers/todoist/`) 3. **Make it executable:** ```bash chmod +x todoist_mcp.py ``` ## Configuration ### For Claude Desktop Add the following 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": ["/path/to/todoist_mcp.py"], "env": { "TODOIST_API_TOKEN": "your_api_token_here" } } } } ``` Replace: - `/path/to/todoist_mcp.py` with the actual path to your server file - `your_api_token_here` with your Todoist API token ### Getting Your Todoist API Token 1. Log in to Todoist 2. Go to Settings → Integrations → Developer 3. Copy your API token 4. Keep it secure - this token provides full access to your Todoist account ## Usage Examples Once configured, you can interact with Todoist through natural language: ### Project Management - "Show me all my Todoist projects" - "Create a new project called 'Q1 Goals' with red color" - "Make my Work project a favorite" - "Change my Personal project to board view" ### Task Management - "What tasks do I have due today?" - "Create a task 'Review quarterly report' in my Work project due tomorrow with high priority" - "Add task 'Call dentist next Monday at 2pm #Health p2'" (uses Quick Add) - "Mark task 123456 as complete" - "Update my 'Buy milk' task to be due tomorrow" - "Show me all tasks with the label 'urgent'" - "List tasks in my Work project" ### Organization - "Create a section called 'In Progress' in my Work project" - "Show me all my labels" - "Create a new label called 'waiting' with blue color" - "Add a comment 'Started working on this' to task 789012" ### Natural Language Quick Add The Quick Add feature understands: - **Projects**: `@ProjectName` or `#ProjectName` - **Labels**: `@LabelName` - **Priority**: `p1`, `p2`, `p3`, `p4` or `!`, `!!`, `!!!` - **Due dates**: `today`, `tomorrow`, `next Monday`, `Jan 15`, etc. Examples: - "Meeting tomorrow at 3pm #Work p2" - "Buy groceries today @Shopping" - "Review document every Friday #Work" ## Available Tools | Tool | Description | |------|-------------| | `todoist_list_projects` | List all projects with hierarchy and metadata | | `todoist_create_project` | Create a new project | | `todoist_update_project` | Update project properties | | `todoist_list_tasks` | List tasks with optional filters | | `todoist_create_task` | Create a task with full control | | `todoist_quick_add_task` | Add task using natural language | | `todoist_update_task` | Update task properties | | `todoist_complete_task` | Mark task as complete | | `todoist_list_sections` | List project sections | | `todoist_create_section` | Create a new section | | `todoist_list_labels` | List personal labels | | `todoist_create_label` | Create a new label | | `todoist_get_comments` | Get comments for task/project | | `todoist_add_comment` | Add a comment | ## Response Formats Most tools support two response formats: - **Markdown** (default): Human-readable formatted text with emojis and structure - **JSON**: Machine-readable format with complete data The server automatically uses the appropriate format based on context. ## Rate Limits Todoist API has the following limits: - Maximum 1000 requests per 15 minutes per user - 1 MB maximum request body size - 15 second processing timeout per request The server provides clear error messages when limits are exceeded. ## Error Handling The server provides clear, actionable error messages: - Invalid API token errors with setup guidance - Rate limit notifications with wait recommendations - Resource not found errors with ID verification hints - Network timeout handling with retry suggestions ## Security Notes - Store your API token securely - never commit it to version control - The API token provides full access to your Todoist account - Use environment variables for token storage - Consider using a separate Todoist account for testing ## Troubleshooting ### Common Issues 1. **"Invalid API token" error:** - Verify your token in Todoist Settings → Integrations → Developer - Ensure the token is correctly set in the configuration 2. **"Resource not found" errors:** - Check that project/task IDs are correct - IDs are now strings in Todoist API v2 3. **Rate limit errors:** - Wait 15 minutes before making more requests - Consider batching operations where possible 4. **Connection timeouts:** - Check your internet connection - Todoist API may be temporarily unavailable ### Debug Mode To see detailed error messages, run the server directly: ```bash TODOIST_API_TOKEN=your_token python todoist_mcp.py ``` ## Development ### Adding New Features The server is built with FastMCP and follows MCP best practices: - Pydantic models for input validation - Comprehensive error handling - Support for both Markdown and JSON responses - Character limit handling for large responses ### Code Structure - **Pydantic Models**: Input validation for all operations - **Utility Functions**: Shared API requests, error handling, formatting - **Tool Definitions**: Each tool with comprehensive docstrings - **Response Formatting**: Markdown and JSON output options ## License MIT License - See LICENSE file for details ## Support For issues or questions: 1. Check the Todoist API documentation: https://developer.todoist.com/rest/v2/ 2. Review MCP documentation: https://modelcontextprotocol.io/ 3. File an issue on the project repository ## Changelog ### Version 1.0.0 (Initial Release) - Complete project management (list, create, update) - Full task operations (CRUD, complete, quick add) - Section and label management - Comment system support - Natural language task creation - Comprehensive error handling - Support for all Todoist filters - Markdown and JSON response formats