# 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