使用说明

Todoist MCP服务器

模型上下文协议（MCP）服务器，使用Todoist的官方REST API v2连接Todoist。此服务器使MCP兼容客户端能够与您的Todoist帐户交互，管理任务、项目、部分、标签和评论。

使用官方Go构建 mcp-go SDK 适用于所有操作系统（Linux、Windows、macOS）。

特性

任务管理 -使用筛选器创建、更新、完成、重新打开、删除和搜索任务
快速添加 -使用Todoist的自然语法快速创建带有内联#project@label p1-p4标签的任务
任务统计 -按项目、优先级、今天和逾期获取汇总统计数据
批量操作 -在意识到速度限制的情况下一次完成多个任务
项目 -列出、创建、更新和删除支持子项目的项目
章节 -使用章节组织项目内的任务
标签 -为任务组织创建和管理个人标签
评论 -添加、更新和删除对任务和项目的评论
自然语言日期 -使用自然语言表示截止日期（“明天下午3点”、“每周一”）
高级筛选 -使用Todoist强大的过滤语法搜索任务
优先级管理 -将任务优先级从p1（紧急）设置为p4（正常）
速率限制 -内置滑动窗口速率限制器（每15分钟450个请求）
断路器 -重复上游故障后自动快速故障，具有自愈恢复功能
并发控制 -限制并发工具执行以防止资源耗尽
秘密行动 -API令牌将自动从所有日志输出中删除
审计日志 -破坏性操作会被记录下来，并附有完整的可追溯性参数
硬化运输 -粒度HTTP超时（拨号、TLS、响应头）和响应正文大小限制
使用回退重试 -具有上下文感知取消功能的瞬态故障自动指数回退
结构化日志记录 -JSON格式的日志，包含相关ID、工具名称和持续时间，通过 slog
交叉平台的 -适用于Linux、Windows和macOS
安全 -使用API令牌（从不使用您的密码）

先决条件

达到1.25或更高 - 安装Go
Todoist帐户 -免费或高级账户 todoist.com
API代币 -Todoist帐户中的个人API令牌（请参阅下面的设置）

获取您的Todoist API代币

要使用此MCP服务器，您需要Todoist的个人API令牌：

首选 Todoist设置>集成
向下滚动到 开发者 部分
复制您的 API令牌 （看起来像： 0123456789abcdef0123456789abcdef01234567)
安全保存此令牌-您需要它进行配置

重要提示：

您的API代币提供对Todoist帐户的完全访问
永远不要共享API令牌或将其提交给版本控制
如果令牌受损，您可以随时重新生成令牌

安装

来源

# Clone the repository
git clone https://github.com/rgabriel/mcp-todoist.git
cd mcp-todoist

# Build the server
go build -o mcp-todoist

# Optional: Install to your PATH
go install

使用go install

go install github.com/rgabriel/mcp-todoist@latest

配置

创建一个 .env 与服务器可执行文件位于同一目录中的文件（用于本地测试）：

cp .env.example .env

编辑 .env 并添加您的API令牌：

TODOIST_API_TOKEN=your_api_token_here

环境变量：

TODOIST_API_TOKEN （必需）-您的Todoist API令牌来自https://todoist.com/prefs/integrations
LOG_LEVEL （可选）-日志详细程度： DEBUG, INFO （默认）， WARN，或 ERROR

使用Claude Desktop

将此服务器添加到您的Claude Desktop配置文件中：

macOS

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "todoist": {
      "command": "/path/to/mcp-todoist",
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

视窗

编辑 %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "todoist": {
      "command": "C:\\path\\to\\mcp-todoist.exe",
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Linux

编辑 ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "todoist": {
      "command": "/path/to/mcp-todoist",
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

添加配置后，重新启动Claude Desktop。

使用Claude Code CLI

使用添加服务器 claude mcp add 命令：

claude mcp add todoist -- /path/to/mcp-todoist

在启动Claude Code之前将API令牌设置为环境变量，或将其导出到您的shell配置文件中：

export TODOIST_API_TOKEN="your_api_token_here"

或者，使用包装器脚本添加一个显式的环境变量：

claude mcp add todoist -- env TODOIST_API_TOKEN=your_api_token_here /path/to/mcp-todoist

要验证服务器是否已注册：

claude mcp list

可用工具

任务管理

1.搜索任务

使用可选筛选器搜索和列出任务。

参数：

filter （可选）-Todoist过滤器语法（请参阅下面的过滤器示例）
project_id （可选）-按特定项目ID筛选
label （可选）-按标签名称筛选
ids （可选）-要检索的任务ID数组

例子：

{
  "filter": "today & p1"
}

示例响应：

{
  "count": 2,
  "tasks": [
    {
      "id": "7654321",
      "content": "Buy groceries",
      "description": "",
      "project_id": "2203306141",
      "priority": 4,
      "due": {
        "date": "2026-02-02",
        "string": "today"
      }
    }
  ]
}

2.任务

获取单个任务的完整详细信息。

参数：

task_id （必需）-要检索的任务ID

例子：

{
  "task_id": "7654321"
}

3.创建任务

创建新任务。

参数：

content （必填）-任务标题
description （可选）-任务描述（支持标记）
project_id （可选）-项目ID
section_id （可选）-项目中的节ID
parent_id （可选）-父任务ID（用于子任务）
order （可选）-任务顺序
labels （可选）-标签名称数组
priority （可选）-优先级从1（正常）到4（紧急/p1）
due_string （可选）-自然语言截止日期
due_date （可选）-到期日期，格式为YYYY-MM-DD
due_datetime （可选）-RFC3339格式的到期日期和时间
assignee_id （可选）-要分配的用户ID（用于共享项目）
duration （可选）-持续时间金额
duration_unit （可选）-持续时间单位：“分钟”或“天”
deadline_date （可选）-YYYY-MM-DD格式的截止日期

例子：

{
  "content": "Finish project proposal",
  "description": "Include budget and timeline",
  "priority": 4,
  "due_string": "tomorrow at 2pm",
  "labels": ["work", "urgent"]
}

4.更新任务

更新现有任务。

参数：

task_id （必需）-要更新的任务ID
create_task中的所有其他参数（可选）

例子：

{
  "task_id": "7654321",
  "content": "Updated task title",
  "priority": 3
}

5.完成任务

将任务标记为已完成。

参数：

task_id （必填）-要完成的任务ID

例子：

{
  "task_id": "7654321"
}

6.未完成任务

重新打开已完成的任务。

参数：

task_id （必需）-要重新打开的任务ID

7.删除任务

永久删除任务。

参数：

task_id （必填）-要删除的任务ID

8.快速任务

使用Todoist的自然语法和内联解析快速添加任务。

参数：

content （必需）-具有内联语法的任务内容

语法：

#ProjectName -分配给项目
@label -添加标签
p1, p2, p3, p4 -设置优先级（p1=紧急，p4=正常）
自然语言日期-“明天”，“下周一下午3点”

例子：

{
  "content": "Buy milk #Shopping @groceries p1 tomorrow at 9am"
}

这解析为：

任务：“买牛奶”
项目：购物
标签：[食品杂货]
优先级：4（p1/紧急）
到期日：明天上午9点

9.任务启动

获取有关任务的汇总统计信息。

参数： 无

示例响应：

{
  "total_active": 47,
  "today": 12,
  "overdue": 3,
  "by_priority": {
    "p1": 5,
    "p2": 10,
    "p3": 15,
    "p4": 17
  },
  "by_project": {
    "Work": 25,
    "Personal": 15,
    "Shopping": 7
  }
}

10.批量完成任务

使用任务ID或筛选器一次完成多个任务。

参数：

task_ids （可选）-要完成的任务ID数组
filter （可选）-Todoist筛选器以选择任务

注：要么 task_ids 或 filter 是必需的。

示例（按ID）：

{
  "task_ids": ["7654321", "7654322", "7654323"]
}

示例（按过滤器）：

{
  "filter": "today & p4"
}

示例响应：

{
  "total_tasks": 15,
  "completed": 15,
  "failed": 0,
  "message": "Successfully completed 15 tasks"
}

速率限制： 对于5个以上的任务，此工具自动使用Sync API批处理在单个请求中完成所有任务，而不是每个任务一个请求。

11.批创建任务

在单个批处理请求中创建多个任务，以实现最高效率。

参数：

tasks （必填）-任务对象数组

每个任务对象可以包括：

content （必填）-任务标题
description （可选）-任务描述
project_id （可选）-项目ID
section_id （可选）-节ID
labels （可选）-标签名称数组
priority （可选）-优先级1-4
due_string （可选）-自然语言截止日期
due_date （可选）-到期日期，格式为YYYY-MM-DD
parent_temp_id （可选）-按索引引用批处理中的另一个任务（例如，第一个任务为“0”）
parent_id （可选）-用作父任务的现有任务ID

示例（独立任务）：

{
  "tasks": [
    {
      "content": "Buy groceries",
      "priority": 3,
      "due_string": "tomorrow"
    },
    {
      "content": "Call dentist",
      "priority": 4,
      "due_string": "today"
    },
    {
      "content": "Review report",
      "priority": 2
    }
  ]
}

示例（有父子关系）：

{
  "tasks": [
    {
      "content": "Project Planning",
      "priority": 4
    },
    {
      "content": "Research phase",
      "parent_temp_id": "0",
      "priority": 3
    },
    {
      "content": "Implementation",
      "parent_temp_id": "0",
      "priority": 2
    }
  ]
}

这将在单个API请求中创建具有两个子任务的父任务。这 parent_temp_id: "0" 引用批处理中的第一个任务（索引0）。

示例响应：

{
  "total_tasks": 3,
  "created": 3,
  "failed": 0,
  "created_tasks": [
    {"index": 0, "id": "7654321", "content": "Project Planning"},
    {"index": 1, "id": "7654322", "content": "Research phase"},
    {"index": 2, "id": "7654323", "content": "Implementation"}
  ],
  "message": "Successfully created 3 tasks in a single batch"
}

优点：

在单个API请求中创建任意数量的任务
支持批处理中的父子任务关系
大幅降低限速消耗
非常适合项目设置、批量导入或创建任务模板

12.移动任务

在单个操作中将多个任务移动到不同的项目中。

参数：

task_ids （可选）-要移动的任务ID数组
filter （可选）-Todoist筛选器字符串，用于选择要移动的任务
to_project_id （必填）-目标项目ID

注：要么 task_ids 或 filter 是必需的，但不是两者都需要。

示例（按ID）：

{
  "task_ids": ["7654321", "7654322", "7654323"],
  "to_project_id": "2203306141"
}

示例（按过滤器）：

{
  "filter": "@someday",
  "to_project_id": "2203306141"
}

示例响应：

{
  "total_tasks": 15,
  "moved": 15,
  "failed": 0,
  "failed_task_ids": [],
  "to_project": "Backlog",
  "used_batching": true,
  "message": "Successfully moved 15 tasks to 'Backlog'"
}

速率限制： 对于5个以上的任务，此工具自动使用同步API批处理来移动单个请求中的所有任务，而不是每个任务一个请求。

优点：

通过在项目之间批量移动任务来组织任务
根据任务数自动选择最佳API（REST与Sync）
支持基于过滤器的选择，以实现灵活的任务定位
通过智能批处理实现最少的API调用

项目

13.列表_项目

列出所有项目。

参数： 无

示例响应：

{
  "count": 3,
  "projects": [
    {
      "id": "2203306141",
      "name": "Work",
      "color": "blue",
      "is_favorite": true,
      "view_style": "list"
    }
  ]
}

14.创建_项目

创建一个新项目。

参数：

name （必填）-项目名称
parent_id （可选）-父项目ID（用于子项目）
color （可选）-项目颜色（例如，“红色”、“蓝色”、“绿色”）
is_favorite （可选）-项目是否为收藏夹
view_style （可选）-视图样式：“列表”或“板”

例子：

{
  "name": "Personal Projects",
  "color": "green",
  "is_favorite": true,
  "view_style": "list"
}

15.get_项目

获取单个项目的详细信息。

参数：

project_id （必需）-要检索的项目ID

16.更新_项目

更新现有项目。

参数：

project_id （必填）-要更新的项目ID
create_project中的所有其他参数（可选）

17.删除项目

删除项目及其所有任务。

参数：

project_id （必填）-要删除的项目ID

章节

18.列表_部分

列出部分，可选择按项目筛选。

参数：

project_id （可选）-按项目ID筛选

19.创建_部分

在项目中创建新节。

参数：

name （必填）-节名称
project_id （必填）-项目ID
order （可选）-分段顺序

20.更新_部分

更新节名称。

参数：

section_id （必填）-要更新的节ID
name （必填）-新节名称

21.删除_部分

删除一个部分。

参数：

section_id （必填）-要删除的节ID

Todoist特定功能

自然语言数据解析

使用 due_string 自然语言参数：

"today" -今天到期
"tomorrow" -明天到期
"next monday" -下周一到期
"tomorrow at 3pm" -明天下午3点到期
"every day" -每天重复
"every monday at 9am" -每周定期，周一上午9:00
"every 2 weeks" -每两周复发一次
"jan 23" -1月23日到期

优先级映射

Todoist使用优先级1-4：

优先级4（p1） -紧急（红旗）
优先级3（p2） -高（橙色旗帜）
优先级2（p3） -中等（黄旗）
优先级1（p4） -正常（无标志）-默认

创建或更新任务时，请使用数字1-4。API接受数值并理解过滤器字符串中的p1-p4表示法。

筛选器语法示例

使用这些过滤器 search_tasks 工具：

基于日期的筛选器：

"today" -今天到期的任务
"tomorrow" -明天到期的任务
"overdue" -逾期任务
"7 days" -未来7天内到期的任务
"no date" -没有截止日期的任务

优先级筛选器：

"p1" -优先级1（紧急）任务
"p2" -优先级2（高）任务
"p3" -优先级3（中等）任务
"p4" -优先级4（正常）任务

标签过滤器：

"@shopping" -带有“购物”标签的任务
"@work" -带有“工作”标签的任务

项目筛选器：

"#Work" -“工作”项目中的任务
"#Personal" -“个人”项目中的任务

组合过滤器：

"today & p1" -今天到期的紧急任务
"overdue & @work" -逾期工作任务
"7 days & p1" -未来7天内到期的紧急任务
"#Work & !assigned to: others" -分配给我的工作任务

搜索运算符：

"search: meeting" -包含“会议”的任务
"created: today" -今天创建的任务
"assigned to: me" -分配给我的任务

有关更多筛选器示例，请参阅 Todoist过滤器文档.

速率限制

Todoist API根据使用的端点有不同的速率限制：

REST API v2

每15分钟450个请求 对于REST端点
被大多数工具使用（搜索、获取、创建、更新、删除单个项目）
服务器会自动跟踪请求，如果接近限制，则返回错误

同步API v1（命令批处理）

单个请求中的多个操作 -大大减少了API调用
自动使用者：
- bulk_complete_tasks -完成5项以上任务时
- batch_create_tasks -用于同时创建多个任务
- move_tasks -当移动超过5个任务时
优点：完成100个任务=1个API请求，而不是100个

效率提升示例：

操作	任务	REST API v2	同步API批处理
完成	2	2个请求	2个
完成	10	10个请求	1个请求
完成	100	100个请求	1个请求
创建	20	20个请求	1个请求

保持在限制范围内的提示：

使用过滤器缩小搜索结果的范围，而不是获取所有任务
使用 batch_create_tasks 或 bulk_complete_tasks 用于多种操作
服务器根据操作大小自动选择最高效的API
避免频繁轮询更新

如果您达到了速率限制，请等待15分钟窗口重置，然后再发出更多请求。

发展

本地运行

# Set environment variables
export TODOIST_API_TOKEN="your_api_token_here"

# Run the server
go run main.go

建筑

# Build for your current platform
go build -o mcp-todoist

# Build for specific platforms
GOOS=linux GOARCH=amd64 go build -o mcp-todoist-linux
GOOS=darwin GOARCH=arm64 go build -o mcp-todoist-macos
GOOS=windows GOARCH=amd64 go build -o mcp-todoist-windows.exe

测试

# Run all tests with race detector
go test -race ./...

# Run linter
golangci-lint run ./...

# Check for vulnerabilities
govulncheck ./...

MCP检验员测试

使用 MCP检查员要测试服务器，请执行以下操作：

npx @modelcontextprotocol/inspector mcp-todoist

故障排除

认证失败

问题： “身份验证失败：API令牌无效”

解决：

验证您正在使用来自的正确API令牌https://todoist.com/prefs/integrations
检查您是否复制了整个令牌（没有空格或额外字符）
如果旧令牌被撤销，则重新生成新令牌
确保在环境变量中正确设置了令牌

超出费率限制

问题： “超出速率限制：请求太多”

解决：

等待15分钟窗口重置
服务器跟踪请求并显示当前计数
减少请求的频率
使用更具体的筛选器来减少API调用的数量

未找到任务/项目

问题： “找不到资源：请求的项目不存在”

解决：

验证ID是否正确（任务ID、项目ID等）
该项目可能已被删除
使用 list_projects 或 search_tasks 找到正确的ID
检查您是否有权访问该项目（对于共享项目）

无效参数

问题： “优先级必须介于1（正常）和4（紧急）之间”

解决：

检查参数值是否与预期格式匹配
优先级必须为1-4（整数）
日期应使用YYYY-MM-DD格式或自然语言
数组（如标签）的格式应正确

网络超时

问题： 连接超时或响应缓慢

解决：

检查您的互联网连接
Todoist API服务器可能暂时不可用
服务器强制执行精细超时（5秒拨号、5秒TLS握手、5秒响应头、总共30秒）
瞬时故障将以指数回退方式自动重试（最多3次尝试）
如果API完全关闭，断路器将在连续5次故障后打开，并在再次探测前立即拒绝请求30秒
尝试在浏览器中访问todoist.com以验证服务状态

建筑

服务器由以下部分组成：

REST API客户端 (todoist/client.go)-用于REST API v2的HTTP客户端包装，具有速率限制、断路器和重试
同步API客户端 (todoist/sync_client.go)-同步API v1客户端，以便使用共享弹性原语进行命令批处理
HTTP传输 (todoist/transport.go)-具有粒度超时和响应体大小限制的共享硬化传输
断路器 (todoist/circuit_breaker.go)-两个客户端共享三个状态断路器（闭合/打开/半打开）
速率限制器 (todoist/rate_limiter.go)-滑动窗口速率限制器（每15分钟450个请求）
配置 (config/config.go)-环境变量加载和验证 file:// 秘密支持
工具操作员 (tools/*.go)-每个操作的MCP工具实施
中间件 (main.go)-并发上限、工具超时、结构化日志记录、审计日志记录和紧急恢复
秘密行动 (redact.go)-定制 slog.Handler 从所有日志输出中清除API令牌

服务器智能地使用这两个API：

REST API v2 用于单个操作（搜索、获取、创建、更新、删除）
同步API v1批处理 用于批量操作（大于5个任务的bulk_complete_tasks、batch_create_tasks）

中间件按以下顺序应用（最外层优先）：

并发上限 （10个并发工具调用）
超时+日志记录+审核 （30秒截止日期、关联ID、破坏性操作的审计跟踪）
恐慌恢复 （内置于SDK中）

依赖项

mcp走 v0.4.3.2-MCP Go SDK
godotenv v1.5.1-环境变量加载器
通用唯一标识符 v1.0.0-同步API命令等性的UUID生成
Go标准库- net/http, encoding/json, context, log/slog

安全注意事项

永远不要承诺你的 .env 文件或API令牌到版本控制
您的API代币提供对Todoist帐户的完全访问
您可以随时从以下位置重新生成令牌https://todoist.com/prefs/integrations
服务器在本地运行，不向第三方发送数据
与Todoist的所有通信都使用HTTPS（TLS加密）
使用环境变量或 file:// 挂载秘密的路径
秘密编辑 确保API令牌被替换为 [REDACTED] 在所有日志输出中（消息、属性、嵌套组）
审核日志记录 记录破坏性操作(delete_*, bulk_complete_tasks, batch_create_tasks, move_tasks)为事件后审查提供完整的请求论据
响应体的大小限制为10MB，以防止格式错误的响应导致内存耗尽
输入验证在模式级别（最小长度、枚举、模式）和通过自定义验证器强制执行

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

贡献

欢迎投稿！请随时提交拉取请求。

支持

对于问题、疑问或功能请求，请在 GitHub.

致谢

与官方合作建造 mcp-go SDK
与集成 Todoist REST API v2
跟随模型上下文协议规格

使用说明

Todoist MCP服务器

特性

先决条件

获取您的Todoist API代币

安装

来源

使用go install

配置

使用Claude Desktop

macOS

视窗

Linux

使用Claude Code CLI

可用工具

任务管理

1.搜索任务

2.任务

3.创建任务

4.更新任务

5.完成任务

6.未完成任务

7.删除任务

8.快速任务

9.任务启动

10.批量完成任务

11.批创建任务

12.移动任务

项目

13.列表_项目

14.创建_项目

15.get_项目

16.更新_项目

17.删除项目

章节

18.列表_部分

19.创建_部分

20.更新_部分

21.删除_部分

标签

22.列表标签

23.创建标签

24.更新标签

25.删除标签

评论

26.获取_注释

27.添加_注释

28.更新_注释

29.删除_意见

Todoist特定功能

自然语言数据解析

优先级映射

筛选器语法示例

速率限制

REST API v2

同步API v1（命令批处理）

发展

本地运行

建筑

测试

MCP检验员测试

故障排除

认证失败

超出费率限制

未找到任务/项目

无效参数

网络超时

建筑

依赖项

安全注意事项

许可证

贡献

支持

致谢

相关 MCP

GitLab项目管理服务器

Primavera P6 XER文件解析服务器

规范工作流管理工具

协议桥接服务器

React开发协议服务