Todoist

★ 1

from naotama2002

Integrates with the Todoist API to manage your tasks and projects.

🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup

#devops #git #maps #translation

Todoist MCP Server

A Model Context Protocol (MCP) server that provides Todoist API integration for AI assistants.

Overview

The Todoist MCP Server allows AI assistants to interact with Todoist, enabling them to manage tasks and projects on behalf of users. This server implements the Model Context Protocol (MCP), providing a standardized interface for AI systems to access Todoist functionality.

Features

Task Management
- Get filter rules and examples for task filtering
- Get tasks with filtering options
- Get task details
- Create new tasks
- Update existing tasks
- Mark tasks as completed
- Delete tasks
Project Management
- Get all projects
- Get project details

Available Tools

Task Management

`todoist_get_task_filter_rules`

Get filter rules and examples for Todoist task filters. This tool helps translate natural language queries into Todoist filter syntax for the todoist_get_tasks tool.

Parameters: None

Example response (Markdown format):

# Introduction to Filters

Filters in Todoist are custom views that display tasks based on specific criteria. You can filter tasks by name, date, project, label, priority, creation date, and more.

## Creating Filters

1. Select "Filters & Labels" in the sidebar
2. Click the add icon next to Filters
3. Enter a name for your filter and change its color (optional)
4. Enter your filter query
5. Click "Add" to save your filter

## Filter Symbols

| Symbol | Meaning | Example |
|--------|---------|--------|
| \| | OR | today \| overdue |
| & | AND | today & p1 |
| ! | NOT | !subtask |
| () | Priority processing | (today \| overdue) & #work |

## Advanced Queries

### Keyword-Based Filters

| Description | Query |
|-------------|-------|
| Tasks containing "meeting" | search: meeting |
| Tasks containing "meeting" scheduled for today | search: meeting & today |

### Date-Based Filters

| Description | Query |
|-------------|-------|
| Tasks for a specific date | date: jan 3 |
| Tasks before a specific date | before: may 5 |
| Tasks with no date | no date |

## Useful Filter Examples

| Description | Query |
|-------------|-------|
| Overdue or today's tasks in "Work" project | (today \| overdue) & #work |
| Tasks with no date | no date |
| Tasks with @waiting label in the next 7 days | 7 days & @waiting |


#### `todoist_get_tasks`

Get a list of tasks with filtering options.

Parameters:
- `projectId` (string, optional): Filter tasks by project ID
- `filter` (string, optional): Todoist filter query using the Todoist filter syntax

Example:
```json
{
  "projectId": "2203306141",
  "filter": "today"
}

`todoist_get_task`

Get details of a specific task.

Parameters:

id (string, required): The unique identifier of the task

Example:

{
  "id": "2995104339"
}

`todoist_create_task`

Create a new task.

Parameters:

content (string, required): The content of the task
description (string, optional): Detailed description or notes for the task
projectId (string, optional): Project ID to assign the task to
parentId (string, optional): Parent task ID for creating subtasks
order (integer, optional): Order value for positioning the task
priority (integer, optional): Task priority: 1 (normal), 2 (medium), 3 (high), 4 (urgent)
dueString (string, optional): Due date in natural language, e.g., 'today', 'tomorrow'
dueDate (string, optional): Due date in YYYY-MM-DD format
dueDatetime (string, optional): Due date and time in RFC3339 format

Example:

{
  "content": "Buy groceries",
  "description": "Need to buy milk, eggs, and bread",
  "projectId": "2203306141",
  "priority": 2,
  "dueString": "tomorrow at 10am"
}

`todoist_update_task`

Update an existing task.

Parameters:

id (string, required): The unique identifier of the task to update
content (string, optional): The new content of the task
description (string, optional): Detailed description or notes for the task
priority (integer, optional): Task priority: 1 (normal), 2 (medium), 3 (high), 4 (urgent)
dueString (string, optional): Due date in natural language
dueDate (string, optional): Due date in YYYY-MM-DD format
dueDatetime (string, optional): Due date and time in RFC3339 format

Example:

{
  "id": "2995104339",
  "content": "Buy groceries and household items",
  "priority": 1
}

`todoist_close_task`

Mark a task as completed.

Parameters:

id (string, required): The unique identifier of the task to mark as completed

Example:

{
  "id": "2995104339"
}

`todoist_delete_task`

Delete a task.

Parameters:

id (string, required): The unique identifier of the task to delete

Example:

{
  "id": "2995104339"
}

Project Management

`todoist_get_projects`

Get a list of all projects.

Parameters: None

`todoist_get_project`

Get details of a specific project.

Parameters:

id (string, required): The unique identifier of the project

Example:

{
  "id": "2203306141"
}

Integration with Claude Desktop

To use the Todoist MCP Server with Claude Desktop, you need to add it to your Claude Desktop configuration.

Download from GitHub Releases

The easiest way to get started is to download a pre-built binary from the GitHub Releases page:

Go to the Releases page and download the latest release for your platform:
- Linux: todoist-mcp-server_Linux_x86_64.tar.gz or todoist-mcp-server_Linux_arm64.tar.gz
- macOS: todoist-mcp-server_Darwin_x86_64.tar.gz or todoist-mcp-server_Darwin_arm64.tar.gz
- Windows: todoist-mcp-server_Windows_x86_64.zip

Extract the archive to get the todoist-mcp-server binary:

# For Linux/macOS
tar -xzf todoist-mcp-server_*_*.tar.gz

# For Windows
# Extract the zip file using Windows Explorer or a tool like 7-Zip

Make the binary executable (Linux/macOS only):
```
chmod +x todoist-mcp-server
```

Optionally, move the binary to a location in your PATH:

# Linux/macOS
sudo mv todoist-mcp-server /usr/local/bin/

# Windows
# Move the .exe file to a location in your PATH

Build from source

Alternatively, you can build the binary from source:

# Build the binary
make build

Configuration

Add the Todoist MCP Server to your Claude Desktop configuration:

HTTP Mode

Run the Todoist MCP Server in HTTP mode:

todoist-mcp-server --mode http --addr :8080

Add the following configuration to your Claude Desktop settings:

{
  "name": "Todoist",
  "description": "Manage Todoist tasks and projects",
  "endpoint": "http://localhost:8080",
  "tools": [
    {
      "name": "todoist_get_task_filter_rules",
      "description": "Get filter rules and examples for Todoist task filters"
    },
    {
      "name": "todoist_get_tasks",
      "description": "Get a list of tasks with filtering options"
    },
    {
      "name": "todoist_get_task",
      "description": "Get details of a specific task"
    },
    {
      "name": "todoist_create_task",
      "description": "Create a new task"
    },
    {
      "name": "todoist_update_task",
      "description": "Update an existing task"
    },
    {
      "name": "todoist_close_task",
      "description": "Mark a task as completed"
    },
    {
      "name": "todoist_delete_task",
      "description": "Delete a task"
    },
    {
      "name": "todoist_get_projects",
      "description": "Get a list of all projects"
    },
    {
      "name": "todoist_get_project",
      "description": "Get details of a specific project"
    }
  ]
}

Stdio Mode

Using Binary

Claude Desktop / Cline, Roo Cline / Windsurf

{
  "mcpServers": {
    "todoist": {
      "command": "/path/to/todoist-mcp-server",
      "args": ["--mode", "stdio"],
      "env": {
        "TODOIST_API_TOKEN": "<YOUR_TODOIST_API_TOKEN>"
      }
    }
  }
}

VSCode

{
  "mcp": {
    "servers": {
      "todoist": {
        "command": "/path/to/todoist-mcp-server",
        "args": ["--mode", "stdio"],
        "env": {
          "TODOIST_API_TOKEN": "<YOUR_TODOIST_API_TOKEN>"
        }
      }
    }
  }
}

Using Docker

Claude Desktop / Cline, Roo Cline / Windsurf

{
  "mcpServers": {
    "todoist": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "TODOIST_API_TOKEN=<YOUR_TODOIST_API_TOKEN>",
        "ghcr.io/naotama2002/todoist-go-mcp-server:latest",
        "--mode",
        "stdio"
      ]
    }
  }
}

VSCode

{
  "mcp": {
    "servers": {
      "todoist": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "-e",
          "TODOIST_API_TOKEN=<YOUR_TODOIST_API_TOKEN>",
          "ghcr.io/naotama2002/todoist-go-mcp-server:latest",
          "--mode",
          "stdio"
        ]
      }
    }
  }
}

Replace /path/to/todoist-mcp-server with the actual path to the binary and <YOUR_TODOIST_API_TOKEN> with your Todoist API token.

In Claude Desktop, go to Settings > Tools > Add Tool, and paste the appropriate JSON configuration.
Save the configuration and restart Claude Desktop if necessary.

Now you can ask Claude to manage your Todoist tasks and projects using natural language.

Development

Project Structure

todoist-go-mcp-server/
├── cmd/
│   ├── test-client/        # Test client for the Todoist API
│   ├── test-mcp-client/    # Test client for the MCP server
│   └── todoist-mcp-server/ # Main MCP server application
├── docs/                   # Documentation
├── pkg/
│   ├── log/                # Logging utilities
│   ├── todoist/            # Todoist API client and tools
│   └── toolsets/           # MCP toolset definitions
└── todo/                   # Implementation plans and notes

Running Tests

make test

Copy & paste — that's it

# Pull the latest image
docker pull ghcr.io/naotama2002/todoist-go-mcp-server:latest

# Or pull a specific version
docker pull ghcr.io/naotama2002/todoist-go-mcp-server:{TAG}

Before it works, you'll need: TODOIST_API_TOKEN

Installation

Prerequisites

Go 1.21 or later (for building from source)
Docker (for Docker installation)
Todoist API token

Building from Source

Clone the repository:

git clone https://github.com/naotama2002/todoist-go-mcp-server.git
cd todoist-go-mcp-server

Install dependencies:

go mod download

Build the binary:

make build

Using Docker

You can also run todoist-mcp-server using Docker, which provides a consistent environment and easier deployment.

Pull from GitHub Container Registry

# Pull the latest image
docker pull ghcr.io/naotama2002/todoist-go-mcp-server:latest

# Or pull a specific version
docker pull ghcr.io/naotama2002/todoist-go-mcp-server:{TAG}

Build locally

# Build the Docker image
docker build -t todoist-mcp-server .

Setup

Set up your Todoist API token:

Create a .envrc file in the root directory with the following content:

export TODOIST_API_TOKEN=your_todoist_api_token

If you're using direnv, run:

direnv allow

Alternatively, you can set the environment variable directly:

export TODOIST_API_TOKEN=your_todoist_api_token

Usage

Running the Server

Binary Usage

HTTP Mode

Run the server in HTTP mode:

go run cmd/todoist-mcp-server/main.go --mode http --addr :8080

Or using the built binary:

./build/todoist-mcp-server --mode http --addr :8080

Standard I/O Mode

Run the server in stdio mode for integration with MCP clients:

go run cmd/todoist-mcp-server/main.go --mode stdio

Or using the built binary:

./build/todoist-mcp-server --mode stdio

Docker Usage

HTTP Mode

# Basic usage with Docker
docker run --rm -it -p 8080:8080 -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode http --addr :8080

# With custom port
docker run --rm -it -p 3000:3000 -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode http --addr :3000

# Using locally built image
docker run --rm -it -p 8080:8080 -e TODOIST_API_TOKEN=your_todoist_api_token \
  todoist-mcp-server --mode http --addr :8080

Standard I/O Mode

# For stdio mode (used with MCP clients)
docker run --rm -i -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode stdio

# Using locally built image
docker run --rm -i -e TODOIST_API_TOKEN=your_todoist_api_token \
  todoist-mcp-server --mode stdio

Command Line Options

The server supports the following command line options:

--mode <mode>: Server mode, either 'http' or 'stdio' (default: "http")
- http: Run as an HTTP server
- stdio: Run using standard input/output for MCP communication
--addr <address>: Address to listen on in HTTP mode (default: ":8080")
--token <token>: Todoist API token (can also be set via TODOIST_API_TOKEN environment variable)

Examples:

# Run HTTP server on port 3000
go run cmd/todoist-mcp-server/main.go --mode http --addr :3000

# Run with a specific Todoist API token
go run cmd/todoist-mcp-server/main.go --mode http --token your_todoist_api_token

# Run in stdio mode
go run cmd/todoist-mcp-server/main.go --mode stdio

Testing with the MCP Client

You can test the server using the included test client:

go run cmd/test-mcp-client/main.go

Troubleshooting

Docker Issues

Port Already in Use

If you get a "port already in use" error, either stop the conflicting service or use a different port:

# Use a different port
docker run --rm -it -p 3335:8080 -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode http --addr :8080

Network Issues with MCP Clients

If MCP clients can't connect to the Docker container, try using host networking:

# Use host networking mode
docker run --rm -i --net=host -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode stdio

Environment Variable Issues

Make sure your Todoist API token is properly set:

# Check if the token is set correctly
docker run --rm -i -e TODOIST_API_TOKEN=your_actual_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode stdio

Clear Authentication Data

If you're having issues with authentication, check your Todoist API token:

Go to Todoist Integrations
Copy your API token
Make sure it's properly set in your environment

Todoist MCP Server

Overview

Features

Available Tools

Task Management

todoist_get_task_filter_rules

todoist_get_task

todoist_create_task

todoist_update_task

todoist_close_task

todoist_delete_task

Project Management

todoist_get_projects

todoist_get_project

Integration with Claude Desktop

Download from GitHub Releases

Build from source

Configuration

HTTP Mode

Stdio Mode

Using Binary

Using Docker

Development

Project Structure

Running Tests

Installation

Prerequisites

Building from Source

Using Docker

Pull from GitHub Container Registry

Build locally

Setup

Usage

Running the Server

Binary Usage

HTTP Mode

Standard I/O Mode

Docker Usage

HTTP Mode

Standard I/O Mode

Command Line Options

Testing with the MCP Client

Troubleshooting

Docker Issues

Port Already in Use

Network Issues with MCP Clients

Environment Variable Issues

Clear Authentication Data

License

`todoist_get_task_filter_rules`

`todoist_get_task`

`todoist_create_task`

`todoist_update_task`

`todoist_close_task`

`todoist_delete_task`

`todoist_get_projects`

`todoist_get_project`