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:

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

2. Install dependencies:

go mod download

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

... [View full README on GitHub](https://github.com/naotama2002/todoist-go-mcp-server#readme)