# Todoist MCP Server (TypeScript)

A Model Context Protocol (MCP) server for interacting with the Todoist API. This server provides CRUD operations for both Tasks and Projects through a standardized MCP interface, built with TypeScript and the official MCP SDK.

## Features

### Project Operations
- ✅ Create new projects
- ✅ Get project details
- ✅ List all projects
- ✅ Update project properties
- ✅ Delete projects

### Task Operations
- ✅ Create new tasks
- ✅ Get task details
- ✅ List tasks with filtering
- ✅ Update task properties
- ✅ Complete tasks
- ✅ Reopen completed tasks
- ✅ Delete tasks

## Setup

### Prerequisites
- Node.js 18+ 
- npm or yarn
- Todoist API token

### Installation

1. Clone or download the server code
2. Install dependencies:
   ```bash
   npm install
   ```

3. Get your Todoist API token:
   - Go to [Todoist Integrations](https://todoist.com/prefs/integrations)
   - Copy your API token

4. Set the environment variable:
   ```bash
   export TODOIST_API_TOKEN=your_token_here
   ```

### Building and Running

```bash
# Build the TypeScript code
npm run build

# Run the server
npm start

# Or build and run in one command
npm run dev

# For development with auto-rebuild
npm run watch
```

## Configuration for Claude Desktop

Add the following to your Claude Desktop configuration file:

**For macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**For Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["-y", "@angdrew/todoist-mcp-server"],
      "env": {
        "TODOIST_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

## Available Tools

### Project Tools

#### `create_project`
Create a new project in Todoist
- **name** (required): Project name
- **color** (optional): Project color
- **viewStyle** (optional): View style ("list" or "board")
- **parentId** (optional): Parent project ID for sub-projects
- **isFavorite** (optional): Mark as favorite

#### `get_project`
Get project details by ID
- **projectId** (required): Project ID

#### `list_projects`
List all projects (no parameters)

#### `update_project`
Update project properties
- **projectId** (required): Project ID
- **name** (optional): New name
- **color** (optional): New color
- **viewStyle** (optional): New view style
- **isFavorite** (optional): Favorite status

#### `delete_project`
Delete a project
- **projectId** (required): Project ID

### Task Tools

#### `create_task`
Create a new task
- **content** (required): Task content
- **description** (optional): Task description
- **projectId** (optional): Project ID
- **dueString** (optional): Due date in natural language
- **dueDate** (optional): Due date (YYYY-MM-DD)
- **dueDatetime** (optional): Due datetime (RFC3339)
- **priority** (optional): Priority 1-4 (4 is highest)
- **labels** (optional): Array of labels

#### `get_task`
Get task details by ID
- **taskId** (required): Task ID

#### `list_tasks`
List tasks with optional filters
- **projectId** (optional): Filter by project ID
- **filter** (optional): Filter expression (e.g., 'today', 'overdue')
- **label** (optional): Filter by label

#### `update_task`
Update task properties
- **taskId** (required): Task ID
- **content** (optional): New content
- **description** (optional): New description
- **dueString** (optional): New due date
- **dueDate** (optional): New due date (YYYY-MM-DD)
- **dueDatetime** (optional): New due datetime
- **priority** (optional): New priority
- **labels** (optional): New labels array

#### `complete_task`
Mark a task as completed
- **taskId** (required): Task ID

#### `reopen_task`
Reopen a completed task
- **taskId** (required): Task ID

#### `delete_task`
Delete a task
- **taskId** (required): Task ID

## Usage Examples

Once configured with Claude Desktop, you can use natural language commands:

- "Create a new project called 'Website Redesign'"
- "List all my projects"
- "Add a task 'Review mockups' to the Website Redesign project"
- "Show me all tasks due today"
- "Mark task 12345 as completed"
- "Update the task content to 'Review and approve mockups'"

## Error Handling

The server includes comprehensive error handling for:
- Invalid API tokens
- Missing required parameters
- API rate limits
- Network errors
- Invalid project/task IDs

## Development

### Building
```bash
npm run build
```

### Watch Mode
```bash
npm run watch
```

### Project Structure
```
src/
├── index.ts          # Main server implementation
├── types.ts          # TypeScript type definitions (optional)
build/                # Compiled JavaScript output
├── index.js
├── index.d.ts
package.json          # Project dependencies and scripts
tsconfig.json         # TypeScript configuration
```

## Dependencies

- **@modelcontextprotocol/sdk**: Official MCP SDK for TypeScript
- **@doist/todoist-api-typescript**: Official Todoist API TypeScript client
- **zod**: Schema validation library

## License

This project is provided as-is for educational and personal use.