todoist-mcp

Todoist MCP 服务

用于 Todoist 任务管理的 Model Context Protocol（MCP）服务，让 Claude 能够与你的 Todoist 任务和项目交互。

功能

• ✅ 创建、读取、更新和完成任务
• 📋 使用高级筛选条件列出任务
• 🔍 按文本内容搜索任务
• 📁 管理项目
• 🏷️ 支持标签和优先级
• 📅 解析自然语言日期
• ⚡ 限流以遵守 API 限制
• 🛡️ 全面的错误处理

安装

前置条件

• Node.js >= 18.0.0
• npm 或 yarn
• 拥有 API 令牌的 Todoist 账号

从源代码安装

# Clone the repository
git clone <your-repo-url>
cd todoist-mcp

# Install dependencies
npm install

# Build the project
npm run build

配置

1. 获取 Todoist API 令牌

1. 前往 Todoist 集成设置
2. 向下滚动到“API token”部分
3. 复制你的个人 API 令牌

2. 设置环境变量

在项目根目录中创建 .env 文件：

cp .env.example .env

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

TODOIST_API_TOKEN=your_actual_token_here
LOG_LEVEL=error

3. 配置 Claude Desktop

将服务添加到 Claude Desktop 配置文件：

位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

配置：

{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": ["/absolute/path/to/todoist-mcp/build/server.js"],
      "env": {
        "TODOIST_API_TOKEN": "your_actual_token_here"
      }
    }
  }
}

重要： 将 /absolute/path/to/todoist-mcp 替换为项目目录的实际绝对路径。

4. 重启 Claude Desktop

更新配置后，重启 Claude Desktop 以使更改生效。

可用工具

todoist_create_task

在 Todoist 中创建新任务，可选设置项目、截止日期、优先级、标签，并指定父任务来创建子任务。

参数：

• content（必填）：任务内容/标题
• description（可选）：任务描述
• project_id（可选）：要添加任务的项目 ID
• section_id（可选）：项目中的分区 ID
• due_date（可选）：自然语言格式或 YYYY-MM-DD 格式的截止日期
• priority（可选）：优先级：1（普通）、2（中）、3（高）、4（紧急）
• labels（可选）：标签名称数组
• parent_id（可选）：用于创建子任务的父任务 ID
• parent_task_name（可选）：要搜索的父任务名称（作为 parent_id 的替代方式）

示例：

Create a task "Write report" due tomorrow with high priority
Create a task "Buy groceries" in the Shopping project
Create a task "Team meeting" due "next Monday at 2pm"
Create a subtask "Buy milk" under parent task "Go to the supermarket"
Create a subtask "Review slides" under task 8237492837
Add subtask "Call John" to the task "Prepare presentation"

todoist_list_tasks

列出活跃任务，可按项目、分区、标签或自定义 Todoist 筛选条件进行筛选。

参数：

• project_id（可选）：按项目 ID 筛选
• section_id（可选）：按分区 ID 筛选
• label（可选）：按标签名称筛选
• filter（可选）：Todoist 筛选查询（例如，“today”、“overdue”、“p1”）
• limit（可选）：返回的最大任务数量（默认：50，最大：200）

示例：

List all my tasks
List tasks in project "Work"
List tasks due today
List all overdue tasks with limit 20

todoist_get_task

获取特定任务的详细信息，包括所有元数据。

参数：

• task_id（必填）：要获取的任务 ID

示例：

Get details for task 123456789
Show me task 987654321

todoist_update_task

更新现有任务的内容、描述、截止日期、优先级或标签。

参数：

• task_id（必填）：要更新的任务 ID
• content（可选）：新的任务内容
• description（可选）：新的任务描述
• due_date（可选）：新的截止日期（自然语言格式或 YYYY-MM-DD）
• priority（可选）：新的优先级（1-4）
• labels（可选）：新的标签数组

示例：

Update task 123 to have priority 4
Change task 456 due date to "next Friday"
Update task 789 content to "Revised meeting agenda"

todoist_complete_task

将任务标记为已完成。

参数：

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

示例：

Complete task 123456
Mark task 789012 as done

todoist_list_projects

列出 Todoist 中的所有项目，包括收件箱和共享项目。

参数： 无

示例：

List all my projects
Show me all my Todoist projects

todoist_search_tasks

按任务内容或描述中的文本搜索任务。

参数：

• query（必填）：要在任务内容和描述中搜索的文本
• limit（可选）：返回的最大任务数量（默认：50，最大：200）

示例：

Search for tasks containing "meeting"
Find all tasks with "budget" in them

开发

构建

npm run build

开发模式（监视）

npm run dev

运行测试

npm test

以监视模式运行测试

npm run test:watch

速率限制

服务遵循 Todoist API 每 15 分钟 450 个请求的速率限制。超出限制时，API 会返回 429 错误，服务会捕获该错误并提供清晰的错误消息。等待一段时间后即可重试请求。

错误处理

所有错误都会返回描述性消息。常见错误包括：

• API 令牌无效：检查 .env 配置或 Claude Desktop 配置
• 未找到任务：确认任务 ID 存在且尚未删除
• 超出速率限制：等待 15 分钟或降低请求频率
• 网络错误：检查网络连接
• 验证错误：检查提供给工具的参数

自然语言日期支持

服务支持 Todoist 的自然语言日期解析。你可以使用以下短语：

• “明天”
• “下周一”
• “每周五”
• “3 天后”
• “下周”
• “12 月 25 日”

你也可以使用标准日期格式：

• “2024-12-31”
• “2024-12-31T14:30:00”

项目结构

todoist-mcp/
├── src/
│   ├── server.ts           # Main MCP server entry point
│   ├── types/              # TypeScript type definitions
│   ├── api/                # Todoist API client and errors
│   ├── tools/              # MCP tool implementations
│   └── utils/              # Utilities (logger, rate limiter)
├── tests/
│   └── unit/               # Unit tests
├── build/                  # Compiled JavaScript output
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

发布与注册表

• MCP 名称： io.github.ecfaria/todoist-mcp
• NPM 包： @ecfaria/todoist-mcp-server
• server.json： 注册表定义见此仓库根目录

发布流程

1. 根据需要更新版本号（npm version <patch|minor|major>）。
2. 构建可分发文件：npm run build。
3. 发布到 npm：npm publish --access public（作用域包默认设为私有）。
4. 验证注册表元数据：mcp-publisher validate。
5. 发布到 MCP 注册表：mcp-publisher publish。

发行说明（v1.0.0）

• 在 package.json 中添加 MCP 注册表元数据（mcpName）。
• 记录发布流程和注册表标识。
• 引入用于注册表发布的规范 server.json 引用。
• 采用作用域 npm 包名称 @ecfaria/todoist-mcp-server，以避免冲突。

故障排除

Claude 中未显示服务

1. 确认 claude_desktop_config.json 中的路径是正确的绝对路径
2. 检查是否已构建项目（npm run build）
3. 确保配置中已设置 API 令牌
4. 完全重启 Claude Desktop

API 令牌无效

1. 前往 Todoist 集成设置
2. 生成新的 API 令牌
3. 更新 .env 文件或 Claude Desktop 配置
4. 重启服务／Claude Desktop

未显示任务

1. 确认使用的是正确的项目 ID 或筛选条件
2. 检查任务是否已完成
3. 尝试不使用筛选条件列出所有任务，以查看可用任务

参与贡献

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

许可证

MIT

支持

• Todoist API 文档
• MCP 文档
• GitHub 问题

致谢

使用以下技术构建：

• Model Context Protocol SDK
• Todoist REST API v2
• TypeScript
• Zod