todoist-v1-mcp-server

一个简洁、可靠的 Todoist MCP (Model Context Protocol) 服务器 —— 基于 Todoist 统一 API v1 构建。

为什么会有这个项目

官方的 Todoist Web MCP (todoist-ai) 在 Anthropic 端存在一个已知的持续断开连接错误，需要每天重新连接。社区的其他替代方案要么是基于已弃用的 REST API v2 构建的，要么存在模式验证错误，导致当 Todoist API 升级并返回额外字段时出现故障。

此服务器：

• 针对 当前的 Todoist API v1（非已弃用的 v2）

• 使用 stdio 传输 —— 无云依赖，无需每日重新连接

• 使用 现代 MCP SDK registerTool() API（非已弃用的 setRequestHandler 模式）

• 从不对 API 响应强制执行严格的输出模式 —— Todoist 可以自由添加新字段而不会导致任何问题

• 无 SDK 包装器依赖 —— 通过 axios 直接进行 HTTP 调用，因此没有与 API 脱节的中间库

工具 (共 20 个)

任务

项目

分区

标签

设置

1. 获取你的 Todoist API 令牌

前往 Todoist → 设置 → 集成 → 开发者 并复制你的 API 令牌。

2. 安装与构建

git clone https://github.com/christulino/todoist-v1-mcp-server
cd todoist-v1-mcp-server
npm install
npm run build

3. 配置 Claude Desktop

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

{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": ["/absolute/path/to/todoist-v1-mcp-server/dist/index.js"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

重启 Claude Desktop。你应该能在已连接的 MCP 服务器中看到 "todoist"。

4. 配置 Claude Code (可选)

claude mcp add todoist -- node /absolute/path/to/todoist-v1-mcp-server/dist/index.js

然后设置环境变量：

export TODOIST_API_TOKEN=your_api_token_here

或者将其添加到你的 shell 配置文件中。

使用示例

连接后，Claude 可以处理如下自然语言指令：

• "What's on my plate today?" (我今天有什么任务？) → 使用 todoist_get_tasks 并传入 filter: "today"

• "Add a task to call the dentist next Tuesday" (添加一个下周二给牙医打电话的任务) → 使用 todoist_create_task

• "Mark the dentist task as done" (将牙医任务标记为已完成) → 使用 todoist_complete_task

• "Show me everything overdue" (显示所有逾期任务) → 使用 todoist_get_tasks 并传入 filter: "overdue"

• "Create a project called Home Renovation" (创建一个名为“房屋装修”的项目) → 使用 todoist_create_project

• "What projects do I have?" (我有哪些项目？) → 使用 todoist_get_projects

Todoist 筛选语法

todoist_get_tasks 中的 filter 参数支持 Todoist 完整的自然语言筛选语法：

完整筛选器文档：https://todoist.com/help/articles/introduction-to-filters

要求

• Node.js 18+

• Todoist 账户（免费版即可）

开发

npm run dev   # tsx watch mode with auto-reload
npm run build # compile TypeScript
npm start     # run compiled server

测试

测试套件会访问真实的 Todoist API，并对任务、项目、分区和标签执行完整的 CRUD 循环。所有测试数据均以 [mcp-test] 为前缀，并会自动清理。

TODOIST_API_TOKEN=your_token npm test

你的 API 令牌位于 Todoist → 设置 → 集成 → 开发者 —— 与你在 claude_desktop_config.json 中填写的令牌相同。

贡献

欢迎提交 PR。目标是实现一个最小化、正确的实现，并与 Todoist API v1 保持同步。优先级：

1. 正确性优于技巧性

2. 宽容的输出处理（绝不拒绝未知的 API 字段）

3. 有用的错误消息，告知你哪里出了问题以及如何修复

许可证

MIT