# Todoist MCP Server

A Model Context Protocol (MCP) server for integrating with the Todoist API. This server provides tools to manage projects, tasks, comments, sections, labels, and user information.

## Features

- **Projects**: Create, read, update, delete, archive, and unarchive projects
- **Tasks**: Create, read, update, delete, close, and reopen tasks with support for due dates, priorities, labels, and assignments
- **Comments**: Create, read, update, and delete comments on tasks and projects
- **Sections**: Create, read, update, and delete sections within projects
- **Labels**: Create, read, update, and delete labels
- **User**: Get user information

## Prerequisites

- Node.js 18+ (required for native fetch API support)
- A Todoist API token (get one from [Todoist Settings > Integrations](https://todoist.com/app/settings/integrations))

## Installation

1. Clone or download this repository
2. Install dependencies:

```bash
npm install
```

3. Build the project:

```bash
npm run build
```

**Note**: If you encounter TypeScript errors about `fetch` or `URLSearchParams` not being found, this is expected during development. These are built-in to Node.js 18+ and will work correctly at runtime. The errors should resolve after installing dependencies.

## Configuration

Set the `TODOIST_API_TOKEN` environment variable with your Todoist API token:

```bash
export TODOIST_API_TOKEN="your-api-token-here"
```

Or create a `.env` file (you'll need to install `dotenv` package if you want to use it):

```
TODOIST_API_TOKEN=your-api-token-here
```

## Usage

### Running the Server

The server communicates via stdio (standard input/output) as per MCP protocol:

```bash
npm start
```

Or for development:

```bash
npm run dev
```

### MCP Client Configuration

To use this server with an MCP client (like Claude Desktop, Cursor, etc.), configure it in your MCP settings. Example configuration:

```json
{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": ["/path/to/todoist-mcp/dist/index.js"],
      "env": {
        "TODOIST_API_TOKEN": "your-api-token-here"
      }
    }
  }
}
```

## Available Tools

### Projects
- `get_projects` - Get all active projects (supports pagination)
- `get_project` - Get a specific project by ID
- `create_project` - Create a new project
- `update_project` - Update an existing project
- `delete_project` - Delete a project
- `archive_project` - Archive a project
- `unarchive_project` - Unarchive a project

### Tasks
- `get_tasks` - Get tasks (supports filtering by project, section, label, and pagination)
- `get_task` - Get a specific task by ID
- `create_task` - Create a new task
- `update_task` - Update an existing task
- `delete_task` - Delete a task
- `close_task` - Close/complete a task
- `reopen_task` - Reopen a completed task

### Comments
- `get_comments` - Get comments (supports filtering by project/task and pagination)
- `create_comment` - Create a comment on a task or project
- `update_comment` - Update a comment
- `delete_comment` - Delete a comment

### Sections
- `get_sections` - Get sections (supports filtering by project and pagination)
- `create_section` - Create a new section
- `update_section` - Update a section
- `delete_section` - Delete a section

### Labels
- `get_labels` - Get all labels (supports pagination)
- `create_label` - Create a new label
- `update_label` - Update a label
- `delete_label` - Delete a label

### User
- `get_user` - Get current user information

## Examples

### Creating a Task

```json
{
  "name": "create_task",
  "arguments": {
    "content": "Buy groceries",
    "project_id": "1234567890",
    "due_string": "tomorrow",
    "priority": 2,
    "labels": ["shopping", "personal"]
  }
}
```

### Getting All Projects

```json
{
  "name": "get_projects",
  "arguments": {
    "limit": 50
  }
}
```

### Creating a Project

```json
{
  "name": "create_project",
  "arguments": {
    "name": "My New Project",
    "color": "berry_red",
    "view_style": "board"
  }
}
```

## API Documentation

For detailed API documentation, see the [Todoist API v1 Documentation](https://developer.todoist.com/api/v1/).

## License

MIT