Todoist MCP Server

Todoist MCP 服务

一个为 AI 助手提供 Todoist API 集成的模型上下文协议（MCP）服务。

概述

Todoist MCP 服务允许 AI 助手与 Todoist 交互，代表用户管理任务和项目。此服务实现了模型上下文协议（MCP），为 AI 系统访问 Todoist 功能提供标准化接口。

功能

• 任务管理

  • 获取任务筛选规则和示例
  • 使用筛选选项获取任务
  • 获取任务详情
  • 创建新任务
  • 更新现有任务
  • 将任务标记为已完成
  • 删除任务

• 项目管理

  • 获取所有项目
  • 获取项目详情

安装

前置条件

• Go 1.21 或更高版本（用于从源代码构建）
• Docker（用于 Docker 安装）
• Todoist API 令牌

从源代码构建

1. 克隆仓库：

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

2. 安装依赖项：

go mod download

3. 构建二进制文件：

make build

使用 Docker

你也可以使用 Docker 运行 todoist-mcp-server，这样可以提供一致的环境并简化部署。

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

设置

设置 Todoist API 令牌：

在根目录中创建一个 .envrc 文件，内容如下：

export TODOIST_API_TOKEN=your_todoist_api_token

如果你使用 direnv，请运行：

direnv allow

或者，你也可以直接设置环境变量：

export TODOIST_API_TOKEN=your_todoist_api_token

使用方法

运行服务

二进制文件用法

HTTP 模式

以 HTTP 模式运行服务：

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

或者使用已构建的二进制文件：

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

标准输入/输出模式

以 stdio 模式运行服务，以便与 MCP 客户端集成：

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

或者使用已构建的二进制文件：

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

Docker 用法

HTTP 模式

# 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

命令行选项

此服务支持以下命令行选项：

• --mode <mode>：服务模式，可选 'http' 或 'stdio'（默认值："http"）
  • http：以 HTTP 服务模式运行
  • stdio：使用标准输入/输出进行 MCP 通信
• --addr <address>：HTTP 模式下的监听地址（默认值：":8080"）
• --token <token>：Todoist API 令牌（也可以通过 TODOIST_API_TOKEN 环境变量设置）

示例：

# 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

使用 MCP 客户端测试

你可以使用随附的测试客户端测试此服务：

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

可用工具

任务管理

todoist_get_task_filter_rules

获取 Todoist 任务筛选器的筛选规则和示例。此工具有助于将自然语言查询转换为 Todoist 筛选语法，供 todoist_get_tasks 工具使用。

参数：无

示例响应（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 |

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

获取特定任务的详情。

参数：

• id（字符串，必填）：任务的唯一标识符

示例：

{
  "id": "2995104339"
}

todoist_create_task

创建新任务。

参数：

• content（字符串，必填）：任务内容
• description（字符串，可选）：任务的详细描述或备注
• projectId（字符串，可选）：要将任务分配到的项目 ID
• parentId（字符串，可选）：用于创建子任务的父任务 ID
• order（整数，可选）：用于确定任务位置的顺序值
• priority（整数，可选）：任务优先级：1（普通）、2（中等）、3（高）、4（紧急）
• dueString（字符串，可选）：自然语言形式的到期日期，例如 'today'、'tomorrow'
• dueDate（字符串，可选）：YYYY-MM-DD 格式的到期日期
• dueDatetime（字符串，可选）：RFC3339 格式的到期日期和时间

示例：

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

todoist_update_task

更新现有任务。

参数：

• id（字符串，必填）：要更新的任务的唯一标识符
• content（字符串，可选）：任务的新内容
• description（字符串，可选）：任务的详细说明或备注
• priority（整数，可选）：任务优先级：1（普通）、2（中）、3（高）、4（紧急）
• dueString（字符串，可选）：使用自然语言表示的截止日期
• dueDate（字符串，可选）：YYYY-MM-DD 格式的截止日期
• dueDatetime（字符串，可选）：RFC3339 格式的截止日期和时间

示例：

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

todoist_close_task

将任务标记为已完成。

参数：

• id（字符串，必填）：要标记为已完成的任务的唯一标识符

示例：

{
  "id": "2995104339"
}

todoist_delete_task

删除任务。

参数：

• id（字符串，必填）：要删除的任务的唯一标识符

示例：

{
  "id": "2995104339"
}

项目管理

todoist_get_projects

获取所有项目的列表。

参数：无

todoist_get_project

获取指定项目的详细信息。

参数：

• id（字符串，必填）：项目的唯一标识符

示例：

{
  "id": "2203306141"
}

与 Claude Desktop 集成

若要在 Claude Desktop 中使用 Todoist MCP Server，需要将其添加到 Claude Desktop 配置中。

从 GitHub Releases 下载

最简单的入门方式是从 GitHub Releases 页面下载预构建的二进制文件：

1. 前往 Releases 页面，下载适用于你平台的最新版本：

   • Linux：todoist-mcp-server_Linux_x86_64.tar.gz 或 todoist-mcp-server_Linux_arm64.tar.gz
   • macOS：todoist-mcp-server_Darwin_x86_64.tar.gz 或 todoist-mcp-server_Darwin_arm64.tar.gz
   • Windows：todoist-mcp-server_Windows_x86_64.zip

2. 解压压缩包，获取 todoist-mcp-server 二进制文件：

   # 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
   

3. 将二进制文件设为可执行文件（仅限 Linux/macOS）：

   chmod +x todoist-mcp-server
   

4. 可选：将二进制文件移至 PATH 中的某个位置：

   # Linux/macOS
   sudo mv todoist-mcp-server /usr/local/bin/
   
   # Windows
   # Move the .exe file to a location in your PATH
   

从源代码构建

或者，你也可以从源代码构建二进制文件：

# Build the binary
make build

配置

将 Todoist MCP Server 添加到 Claude Desktop 配置中：

HTTP 模式

1. 以 HTTP 模式运行 Todoist MCP Server：

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

2. 将以下配置添加到 Claude Desktop 设置中：

{
  "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 模式

使用二进制文件

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

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

将 /path/to/todoist-mcp-server 替换为二进制文件的实际路径，并将 <YOUR_TODOIST_API_TOKEN> 替换为你的 Todoist API 令牌。

1. 在 Claude Desktop 中，前往 Settings > Tools > Add Tool，然后粘贴相应的 JSON 配置。

2. 保存配置，并在需要时重启 Claude Desktop。

现在，你可以使用自然语言让 Claude 管理 Todoist 任务和项目。

贡献

欢迎贡献！请随时提交 Pull Request。

故障排除

Docker 问题

端口已被占用

如果遇到“端口已被占用”错误，请停止冲突的服务或使用其他端口：

# 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

MCP 客户端的网络问题

如果 MCP 客户端无法连接到 Docker 容器，请尝试使用主机网络：

# 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

环境变量问题

请确保已正确设置 Todoist API 令牌：

# 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

清除身份验证数据

如果遇到身份验证问题，请检查 Todoist API 令牌：

1. 前往 Todoist Integrations
2. 复制你的 API 令牌
3. 确保已在环境中正确设置

许可证

本项目采用 MIT License 许可协议，详情请参阅 LICENSE 文件。

Acknowledgments

• Todoist API
• Model Context Protocol

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