This Todoist MCP Server provides an MCP-compliant interface to interact with Todoist, enabling AI assistants to manage tasks and projects on behalf of users. It exposes a set of tools that translate natural language requests into Todoist actions, including listing and filtering tasks, retrieving task details, creating and updating tasks, marking tasks complete, and fetching project information. You can connect to the server using an MCP client (over HTTP in this setup) and invoke the available tools to perform common Todoist workflows such as creating a task with a due date, updating task details, or querying tasks by filters. The server handles authentication via a Todoist API token supplied through environment variables, so your client only needs to send the intended MCP messages and parameters.

Available tools map directly to Todoist operations:

• todoist_get_task_filter_rules: Retrieve filter rules and example queries to help construct Todoist-compatible filters for listing tasks.
• todoist_get_tasks: Get a list of tasks with optional project and filter parameters.
• todoist_get_task: Retrieve details for a specific task by its ID.
• todoist_create_task: Create a new task with fields like content, description, projectId, priority, and due date information.
• todoist_update_task: Update an existing task's content, description, priority, and due date values.
• Todoist project methods (e.g., get all projects, get project details) to support project-level queries.

To use these tools, connect your MCP client to the server (default host/port as per your deployment) and call the appropriate tool with its parameters. The client will receive structured responses suitable for integration into AI assistant workflows, enabling actions such as adding a task, adjusting due dates, or listing tasks that match a given filter.

Prerequisites:

• Go 1.21 or later, for building from source
• Docker (optional, for containerized deployment)
• Todoist API token

Installation steps (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 or run in development mode

   Build the binary (via Makefile targets if provided)

   make build

   Or run directly from source

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

4. Run in HTTP mode (example) go run cmd/todoist-mcp-server/main.go --mode http --addr :8080

Using Docker (optional): 5) Pull and run the prebuilt image docker pull ghcr.io/naotama2002/todoist-go-mcp-server:latest docker run --rm -e TODOIST_API_TOKEN=your_todoist_api_token -p 8080:8080 ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode http --addr :8080

Environment setup for Todoist API token: see next section.

Environment variables and configuration:

• TODOIST_API_TOKEN: Your Todoist API token. This is required for authenticating with Todoist. Can be provided via environment variable or anenv-like setup (e.g., direnv).
• If running locally, ensure the token is exported in your shell: export TODOIST_API_TOKEN=your_todoist_api_token
• In Docker, pass the token as an environment variable: -e TODOIST_API_TOKEN=your_todoist_api_token

Common issues:

• Invalid or missing Todoist API token will result in authentication errors from the Todoist API.
• Ensure the server is accessible on the expected port and that the MCP client is configured to communicate with the host/port.
• When using stdio mode for MCP, ensure the client supports MCP protocol framing.

Tips:

• If you need to run behind a reverse proxy, configure TLS termination at the proxy and point the MCP client to the appropriate HTTP endpoint.
• Regularly rotate your Todoist API token and update the environment variable accordingly.