# 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.
