todoist-go-mcp-server

This project is a Go implementation of an MCP server that leverages the Todoist REST API v2.

1 stars GoOthers Updated Aug 7, 2026

Documentation

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

Installation

Prerequisites

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

Building from Source

1. Clone the repository:

bash

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

2. Install dependencies:

bash

go mod download

3. Build the binary:

bash

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

bash

# 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

bash

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

bash

export TODOIST_API_TOKEN=your_todoist_api_token

If you're using direnv, run:

bash

direnv allow

Alternatively, you can set the environment variable directly:

bash

export TODOIST_API_TOKEN=your_todoist_api_token

Usage

Running the Server

Binary Usage

HTTP Mode

Run the server in HTTP mode:

bash

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

Or using the built binary:

bash

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

Standard I/O Mode

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

bash

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

Or using the built binary:

bash

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

Docker Usage

HTTP Mode

bash

# 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

bash

# 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 `: 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 to listen on in HTTP mode (default: ":8080")
`--token `: Todoist API token (can also be set via TODOIST_API_TOKEN environment variable)

Examples:

bash

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

bash

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

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

markdown

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

code

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

{

"projectId": "2203306141",

"filter": "today"

}

code

#### `todoist_get_task`

Get details of a specific task.

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

Example:

{

"id": "2995104339"

}

code

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

}

code

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

}

code

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

}

code

#### `todoist_delete_task`

Delete a task.

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

Example:

{

"id": "2995104339"

}

code

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

}

code

## 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](https://github.com/naotama2002/todoist-go-mcp-server/releases):

1. Go to the [Releases page](https://github.com/naotama2002/todoist-go-mcp-server/releases) 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`

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

code

3. Make the binary executable (Linux/macOS only):

chmod +x todoist-mcp-server

code

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

code

### Build from source

Alternatively, you can build the binary from source:

Build the binary

make build

code

### Configuration

Add the Todoist MCP Server to your Claude Desktop configuration:

#### HTTP Mode

1. Run the Todoist MCP Server in HTTP mode:

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

code

2. 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"

}

]

}

code

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

}

code

VSCode

{

"mcp": {

"servers": {

"todoist": {

"command": "/path/to/todoist-mcp-server",

"args": ["--mode", "stdio"],

"env": {

"TODOIST_API_TOKEN": ""

}

code

##### Using Docker

Claude Desktop / Cline, Roo Cline / Windsurf

{

"mcpServers": {

"todoist": {

"command": "docker",

"args": [

"run",

"--rm",

"-i",

"-e",

"TODOIST_API_TOKEN=",

"ghcr.io/naotama2002/todoist-go-mcp-server:latest",

"--mode",

"stdio"

]

}

code

VSCode

{

"mcp": {

"servers": {

"todoist": {

"command": "docker",

"args": [

"run",

"--rm",

"-i",

"-e",

"TODOIST_API_TOKEN=",

"ghcr.io/naotama2002/todoist-go-mcp-server:latest",

"--mode",

"stdio"

]

}

code

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

1. In Claude Desktop, go to Settings > Tools > Add Tool, and paste the appropriate JSON configuration.

2. Save the configuration and restart Claude Desktop if necessary.

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

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

code

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

code

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

code

### Clear Authentication Data

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

1. Go to [Todoist Integrations](https://todoist.com/prefs/integrations)
2. Copy your API token
3. Make sure it's properly set in your environment

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [Todoist API](https://developer.todoist.com/api/v1/)
- [Model Context Protocol](https://github.com/mcp-sh/mcp)

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

code

### Running Tests

make test

code

// Code block

Frequently asked questions

What is todoist-go-mcp-server?

todoist-go-mcp-server is This project is a Go implementation of an MCP server that leverages the Todoist REST API v2.

How do I install todoist-go-mcp-server?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is todoist-go-mcp-server open source?

Yes — it is hosted on GitHub at https://github.com/naotama2002/todoist-go-mcp-server and has 1 stars.

Related MCP tools

kubeshark

eBPF-powered network observability for Kubernetes. Indexes L4/L7 traffic with full K8s context, decrypts TLS without keys. Queryable by AI agents via MCP and humans via dashboard.

12,068 Go

kubernetesgolangrest+17

go-whatsapp-web-multidevice

GOWA - WhatsApp REST API with support for UI, Multi Account, Webhooks, and MCP, and Chatwoot. Built with Golang for efficient memory use.

4,717 Go

whatsappwhatsapp-apiwhatsapp-api-go+9

radar

The missing open-source Kubernetes UI with a built-in MCP server for AI agents. See what's broken, why, and what changed. Issues, Topology, event timeline, Helm, GitOps, live service traffic, and cluster audits - all in one Go binary.

3,246 Go

argocdcloud-nativegitops+17

mcp-language-server

mcp-language-server gives MCP enabled clients access semantic tools like get definition, references, rename, and diagnostics.

1,587 Go

ailanguage-server-protocolmcp+2

terraform-mcp-server

The Terraform MCP Server provides seamless integration with Terraform ecosystem, enabling advanced automation and interaction capabilities for Infrastructure as Code (IaC) development.

1,522 Go

matlab-mcp-server

Run MATLAB® using AI applications with the official MATLAB MCP Server from MathWorks®. This MCP server for MATLAB supports a wide range of coding agents like Claude Code® and Visual Studio® Code.

1,461 Go

engineering-toolsmatlabmcp-server+2

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP