Todoist MCP Server MCP Server

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

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 theModel Context Protocol (MCP), providing a standardized interface for AI systems to access Todoist functionality.

- 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

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

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

You can also runtodoist-mcp-serverusing Docker, which provides a consistent environment and easier deployment.

# 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 the Docker image docker build -t todoist-mcp-server .

Create a.envrcfile in the root directory with the following content:

export TODOIST_API_TOKEN=your_todoist_api_token

Alternatively, you can set the environment variable directly:

export TODOIST_API_TOKEN=your_todoist_api_token

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

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

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

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

# 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

# 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

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

# 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

You can test the server using the included test client:

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

# 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" }


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

{ "id": "2995104339" }



- 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

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



- 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

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

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

{ "id": "2995104339" }



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

{ "id": "2995104339" }



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

{ "id": "2203306141" }



To use the Todoist MCP Server with Claude Desktop, you need to add it to your Claude Desktop configuration.
The easiest way to get started is to download a pre-built binary from theGitHub Releases page:

-

Go to theReleases pageand download the latest release for your platform:

- Linux:todoist-mcp-server_Linux_x86_64.tar.gzortodoist-mcp-server_Linux_arm64.tar.gz

- macOS:todoist-mcp-server_Darwin_x86_64.tar.gzortodoist-mcp-server_Darwin_arm64.tar.gz

- Windows:todoist-mcp-server_Windows_x86_64.zip
Extract the archive to get thetodoist-mcp-serverbinary:

# 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): 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

Alternatively, you can build the binary from source: Add the Todoist MCP Server to your Claude Desktop configuration: - 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" } ] }

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>" } } } }

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

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" ] } } }

{ "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-serverwith 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. Contributions are welcome! Please feel free to submit a Pull Request. 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

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

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



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

- Go toTodoist Integrations

- Copy your API token

- Make sure it's properly set in your environment
This project is licensed under the MIT License - see theLICENSEfile for details.

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

```

Manage time tracking, projects, clients, and tasks using the Harvest API.

An MCP server for integrating Todoist with Cursor AI. Requires a Todoist API token.

Manage TimeCamp time entries and tasks through its API.

Interact with the Todoist API to manage your tasks using natural language.

Interact with task, doc, and project data in Dart, an AI-native project management tool

Magica is your all-in-one AI platform, offering 2500+ cutting-edge tools under a single subscription.

Todoist MCP Server

About

Details

Jump to

About

Details

Jump to

More like this

Time

GitLab

Github SSE

Npx Y convex@latest mcp start

FastAPI-MCP

Inbox Zero