mcpField
T
todoist

todoist

github.com/steveclarke生产力3643 次安装今天更新
代码仓库

关于 todoist

todoist 是面向 Todoist 的 MCP 集成说明，适用于希望通过 AI 客户端管理任务和项目的用户。它介绍 API token 与 OAuth 两种连接方式，并列出搜索、创建、更新及完成任务等工具。

主要功能

  1. 01支持 API token 与 OAuth 配置
  2. 02按文本、项目、日期等查找任务
  3. 03创建、更新及完成任务
  4. 04管理项目、分区和评论
  5. 05提供连接故障排查指引

适用场景

  1. 01查询今天及逾期任务
  2. 02在项目中创建并组织任务
  3. 03更新任务安排或标记完成

MCP 相关

该集成通过 Todoist MCP 服务向客户端提供任务、项目、分区和评论相关工具。可使用 API token 配置的 NPX 方式或 HTTP OAuth 连接。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/steveclarke/dotfiles --skill todoist

安装后在 Claude Code 中输入/todoist确认已加载。

详细介绍

Todoist MCP 集成

设置

配置 Todoist MCP 服务有两种方式。日常使用推荐 带 API 令牌的 NPX 版本。

选项 1：使用 API 令牌的 NPX（推荐）

此版本使用 Todoist API 令牌，无需重新进行身份验证。最适合日常使用。

1. 获取 API 令牌：

2. 添加到 ~/.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）。

3. 重启 Claude Code，以应用新配置。

选项 2：使用 OAuth 的 HTTP（替代方案）

此版本使用 OAuth，需要定期重新进行身份验证（会话约 1 小时后过期）。如果不想存储令牌，可以使用此方式。

claude mcp add --transport http todoist https://ai.todoist.net/mcp

在 Claude Code 中，运行 /mcp 打开 MCP 面板。点击 Todoist 并完成 OAuth 流程。

**注意：**OAuth 会话经常超时。如果遇到连接错误，请通过 /mcp 重新进行身份验证。

故障排除

MCP 显示“failed”或无法连接：

  1. 确认环境变量是 TODOIST_API_KEY（而不是 TODOIST_API_TOKEN）
  2. 在 Todoist 开发者设置中重新生成 API 令牌——旧令牌可能已过期
  3. 修改配置后重启 Claude Code
  4. 使用 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获取用户详情、时区和目标

创建任务的最佳实践

根据口头描述创建任务时：

  1. 提炼出简洁、可执行的标题——不要原样照搬口述内容
  2. 在描述中记录上下文——包括“原因”、理由和验收标准
  3. 不要遗漏信息——提及的所有内容都应记录在标题或描述中
  4. 使用祈使句形式——用“联系 Wade”，而不是“正在联系 Wade”
MCP 任务选项
content: "Task title" (required)
description: "Additional details"
dueString: "tomorrow at 5pm" (natural language)
priority: "p1" | "p2" | "p3" | "p4" (p1 = highest)
projectId: "<project-id>" or "inbox"
sectionId: "<section-id>"
labels: ["label1", "label2"]
duration: "2h" | "90m" | "2h30m"
responsibleUser: "<name>" (for shared projects)

常见操作

列出今天的任务

使用 find-tasks-by-date 并设置 startDate: "today"——这会包含逾期任务。

列出项目中的任务

使用 find-tasks 并指定 projectId。收件箱使用 "inbox"，也可以通过 find-projects 获取项目 ID。

移动任务

使用 update-tasks 并将 projectId 设置为目标项目 ID。

分配任务（共享项目）

使用 update-tasks 并指定 responsibleUser。注意：任务位于收件箱时无法分配——请先移动任务，再进行分配。

快速概览

不带参数调用 get-overview 可查看所有项目。添加 projectId 可查看指定项目及其任务。

迁移说明

之前的 CLI 工具（通过 Homebrew 安装的 todoist 命令）存在可靠性问题——移动任务不起作用，同步也不可靠。推荐使用 Doist 官方 MCP 服务。

如果仍安装了 CLI：

brew uninstall todoist

评论

支持 Markdown