Todoist MCP 集成用于让 AI 助手通过 MCP 协议与 Todoist 交互，适用场景为添加任务、列出任务、标记完成或管理项目。
配置方式 提供两种方式配置 Todoist MCP 服务器。推荐日常使用带 API Token 的 NPX 版本。
方式一：NPX 配合 API Token（推荐） 该版本使用 Todoist API Token，不需要重新认证，适合常规使用。
-
获取 API Token：进入 Todoist 设置 → 集成 → 开发者，复制 API Token（或生成新的）。
-
将以下内容添加到 ~/.claude.json 顶层： { "mcpServers": { "todoist": { "command": "npx", "args": ["-y", "@doist/todoist-ai"], "env": { "TODOIST_API_KEY": "your-api-token-here" } } } }
重要：环境变量必须是 TODOIST_API_KEY（不是 TODOIST_API_TOKEN）。
- 重启 Claude Code 以加载新配置。
方式二：HTTP 配合 OAuth（备选） 该版本使用 OAuth，需要定期重新认证（会话约 1 小时后过期）。适合不想存储 Token 的情况。
命令： claude mcp add --transport http todoist https://ai.todoist.net/mcp
在 Claude Code 中运行 /mcp 打开 MCP 面板，点击 Todoist 并完成 OAuth 流程。
注意：OAuth 会话经常超时。如遇连接错误，通过 /mcp 重新认证。
故障排查 MCP 显示“failed”或无法连接时：
- 确认环境变量是 TODOIST_API_KEY（不是 TODOIST_API_TOKEN）
- 在 Todoist 开发者设置中重新生成 API Token——旧 Token 可能已过期
- 修改配置后重启 Claude Code
- 使用 mcp__todoist__user-info 测试连接
可用的 MCP 工具 所有工具以 mcp__todoist__ 为前缀：
- find-tasks：按文本、项目、分区、标签或负责人搜索任务
- find-tasks-by-date：获取某日期范围内的任务（使用 startDate: "today" 获取今天及逾期）
- add-tasks：创建一个或多个任务，支持完整选项
- update-tasks：修改现有任务（移动、日期、优先级、描述、分配）
- complete-tasks：将任务标记为完成
- find-projects：列出或搜索项目
- find-sections：列出项目内的分区
- get-overview：所有项目或指定项目的 Markdown 概览
- add-projects：创建新项目
- add-sections：在项目中创建分区
- add-comments：为任务或项目添加评论
- find-comments：获取任务或项目的评论
- search：跨任务和项目全文搜索
- user-info：获取用户详情、时区、目标
从口头描述创建任务的最佳实践
- 提取干净、可执行的标题——不要原样倾倒原始文本
- 在描述中记录上下文——“为什么”、理由、验收标准
- 不要丢失信息——所有说到的内容都应被记录（标题或描述）
- 使用祈使语气——“Contact Wade”而不是“Contacting Wade”
MCP 任务选项
- content: "Task title"（必填）
- description: "Additional details"
- dueString: "tomorrow at 5pm"（自然语言）
- priority: "p1" | "p2" | "p3" | "p4"（p1 最高）
- projectId: "<project-id>" 或 "inbox"
- sectionId: "<section-id>"
- labels: ["label1", "label2"]
- duration: "2h" | "90m" | "2h30m"
- responsibleUser: "<name>"（用于共享项目）
常见操作
- 列出今日任务：find-tasks-by-date 配合 startDate: "today"，包含逾期项。
- 列出某项目任务：find-tasks 配合 projectId。收件箱用 "inbox"，项目 ID 可通过 find-projects 获取。
- 移动任务：update-tasks 将 projectId 设为目标项目 ID。
- 分配任务（共享项目）：update-tasks 配合 responsibleUser。注意：任务在收件箱时无法分配——先移动再分配。
- 快速概览：get-overview 不带参数获取所有项目；添加 projectId 获取指定项目及其任务。
迁移说明 此前的 CLI 工具（通过 Homebrew 的 todoist 命令）存在可靠性问题——移动无效、同步不可靠。Doist 官方 MCP 服务器是推荐方案。如仍安装有 CLI： brew uninstall todoist
限制：OAuth 方式会话经常超时需重新认证；收件箱中的任务无法直接分配负责人；其余产品功能、收费与价格等信息暂未提供。