clickup-automation

通过 Rube MCP 实现 ClickUp 自动化

通过 Composio 的 ClickUp 工具包，自动化 ClickUp 项目管理工作流，包括创建和更新任务、浏览工作区层级、添加评论以及管理团队成员。

工具包文档：composio.dev/toolkits/clickup

前提条件

• 必须已连接 Rube MCP（可使用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 ClickUp 连接，工具包为 clickup
• 始终先调用 RUBE_SEARCH_TOOLS，以获取当前工具架构

设置

获取 Rube MCP：在客户端配置中添加 https://rube.app/mcp 作为 MCP 服务。无需 API 密钥，只需添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 能正常响应，以验证 Rube MCP 是否可用
2. 调用 RUBE_MANAGE_CONNECTIONS，并指定工具包 clickup
3. 如果连接状态不是 ACTIVE，请按照返回的授权链接完成 ClickUp OAuth
4. 在运行任何工作流之前，确认连接状态显示为 ACTIVE

核心工作流

1. 创建和管理任务

适用场景：用户想要创建任务或子任务、更新任务属性，或列出 ClickUp 列表中的任务。

工具调用顺序：

1. CLICKUP_GET_AUTHORIZED_TEAMS_WORKSPACES - 获取工作区／团队 ID［前置步骤］
2. CLICKUP_GET_SPACES - 列出工作区中的空间［前置步骤］
3. CLICKUP_GET_FOLDERS - 列出空间中的文件夹［前置步骤］
4. CLICKUP_GET_FOLDERLESS_LISTS - 获取不属于任何文件夹的列表［可选］
5. CLICKUP_GET_LIST - 验证列表并检查可用状态［前置步骤］
6. CLICKUP_CREATE_TASK - 在目标列表中创建任务［必需］
7. CLICKUP_CREATE_TASK（使用 parent）- 在父任务下创建子任务［可选］
8. CLICKUP_UPDATE_TASK - 修改任务状态、负责人、日期和优先级［可选］
9. CLICKUP_GET_TASK - 获取完整任务详情［可选］
10. CLICKUP_GET_TASKS - 根据筛选条件列出列表中的所有任务［可选］
11. CLICKUP_DELETE_TASK - 永久删除任务［可选］

CLICKUP_CREATE_TASK 的关键参数：

• list_id：目标列表 ID（整数，必需）
• name：任务名称（字符串，必需）
• description：任务详细描述
• status：必须与目标列表中配置的某个状态名称完全一致（区分大小写）
• priority：1（紧急）、2（高）、3（普通）、4（低）
• assignees：用户 ID 数组（整数）
• due_date：Unix 时间戳，单位为毫秒
• parent：用于创建子任务的父任务 ID 字符串
• tags：标签名称字符串数组
• time_estimate：预计耗时，单位为毫秒

注意事项：

• status 区分大小写，且必须与列表中已有的状态一致；使用 CLICKUP_GET_LIST 检查可用状态
• due_date 和 start_date 是以毫秒为单位的 Unix 时间戳，而非秒
• 子任务的 parent 必须是同一列表中的任务，不能是另一个子任务
• notify_all 会触发关注者通知；批量操作时应设为 false
• 重试可能导致重复创建；请跟踪已创建的任务 ID，以避免重复创建
• 里程碑的 custom_item_id（ID 1）受工作区套餐配额限制

2. 浏览工作区层级结构

使用场景：用户想要浏览或管理 ClickUp 工作区结构（Workspaces > Spaces > Folders > Lists）。

工具调用顺序：

1. CLICKUP_GET_AUTHORIZED_TEAMS_WORKSPACES - 列出所有可访问的工作区 [必需]
2. CLICKUP_GET_SPACES - 列出工作区中的空间 [必需]
3. CLICKUP_GET_SPACE - 获取特定空间的详细信息 [可选]
4. CLICKUP_GET_FOLDERS - 列出空间中的文件夹 [必需]
5. CLICKUP_GET_FOLDER - 获取特定文件夹的详细信息 [可选]
6. CLICKUP_CREATE_FOLDER - 在空间中新建文件夹 [可选]
7. CLICKUP_GET_FOLDERLESS_LISTS - 列出不属于任何文件夹的列表 [必需]
8. CLICKUP_GET_LIST - 获取列表详情，包括状态和自定义字段 [可选]

关键参数：

• team_id：来自 GET_AUTHORIZED_TEAMS_WORKSPACES 的工作区 ID（获取空间时必需）
• space_id：空间 ID（获取文件夹和无文件夹列表时必需）
• folder_id：文件夹 ID（调用 GET_FOLDER 时必需）
• list_id：列表 ID（调用 GET_LIST 时必需）
• archived：用于筛选已归档/活跃项目的布尔值

注意事项：

• ClickUp 层级结构为：Workspace（Team）> Space > Folder > List > Task
• 列表可以直接位于空间下（无文件夹），也可以位于文件夹中
• 必须使用 CLICKUP_GET_FOLDERLESS_LISTS 查找不在文件夹中的列表；CLICKUP_GET_FOLDERS 只会返回文件夹
• ClickUp API 中的 team_id 指工作区 ID，而不是用户组

3. 为任务添加评论

使用场景：用户想要添加评论、查看现有评论或管理任务评论串。

工具调用顺序：

1. CLICKUP_GET_TASK - 验证任务是否存在并获取 task_id [前置条件]
2. CLICKUP_CREATE_TASK_COMMENT - 为任务添加新评论 [必需]
3. CLICKUP_GET_TASK_COMMENTS - 列出任务的现有评论 [可选]
4. CLICKUP_UPDATE_COMMENT - 编辑评论文本、受派人或解决状态 [可选]

CLICKUP_CREATE_TASK_COMMENT 的关键参数：

• task_id：任务 ID 字符串（必需）
• comment_text：评论内容，支持 ClickUp 格式（必需）
• assignee：分配此评论的用户 ID（必需）
• notify_all：是否通知所有关注者，true/false（必需）

CLICKUP_GET_TASK_COMMENTS 的关键参数：

• task_id：任务 ID 字符串（必需）
• start / start_id：用于分页获取较早评论的参数（每页最多 25 条）

注意事项：

• CLICKUP_CREATE_TASK_COMMENT 的四个字段均为必填：task_id、comment_text、assignee 和 notify_all
• 评论的 assignee 是将评论（而不是任务）分配给该用户
• 评论按每页 25 条分页；使用 start（Unix 毫秒）和 start_id 获取较早的页面
• CLICKUP_UPDATE_COMMENT 的四个字段均为必填：comment_id、comment_text、assignee、resolved

4. 管理团队成员和分配

使用场景：用户想要查看工作区成员、检查席位使用情况或查找用户详情。

工具调用顺序：

1. CLICKUP_GET_AUTHORIZED_TEAMS_WORKSPACES - 列出工作区并获取 team_id [必需]
2. CLICKUP_GET_WORKSPACE_SEATS - 检查席位使用情况（成员与访客）[必需]
3. CLICKUP_GET_TEAMS - 列出工作区内的用户组 [可选]
4. CLICKUP_GET_USER - 获取特定用户的详细信息（仅限 Enterprise）[可选]
5. CLICKUP_GET_CUSTOM_ROLES - 列出自定义权限角色 [可选]

关键参数：

• team_id：工作区 ID（所有团队操作均必需）
• user_id：调用 GET_USER 时使用的特定用户 ID
• group_ids：用于筛选团队的逗号分隔用户组 ID

注意事项：

• CLICKUP_GET_WORKSPACE_SEATS 返回席位数量，而非成员详情；请区分成员和访客
• CLICKUP_GET_TEAMS 返回用户组，而非工作区成员；用户组为空不代表没有成员
• CLICKUP_GET_USER 仅适用于 ClickUp Enterprise Plan
• 在多工作区设置中，必须对每个工作区分别查询席位使用情况

5. 筛选和查询任务

使用时机：用户想根据特定条件（状态、受派人、日期、标签、自定义字段）查找任务。

工具调用顺序：

1. CLICKUP_GET_TASKS - 按多个条件筛选列表中的任务［必需］
2. CLICKUP_GET_TASK - 获取单个任务的完整详情［可选］

CLICKUP_GET_TASKS 的关键参数：

• list_id：列表 ID（整数，必需）
• statuses：用于筛选的状态字符串数组
• assignees：用户 ID 字符串数组
• tags：标签名称字符串数组
• due_date_gt / due_date_lt：日期范围的 Unix 时间戳，单位为毫秒
• include_closed：是否包含已关闭的任务（布尔值）
• subtasks：是否包含子任务（布尔值）
• order_by："id"、"created"、"updated" 或 "due_date"
• page：页码，从 0 开始（每页最多 100 个任务）

注意事项：

• 只会返回归属列表与 list_id 匹配的任务；不包含子列表中的任务
• 日期筛选使用 Unix 时间戳，单位为毫秒
• 状态字符串必须完全匹配；空格需使用 URL 编码（例如 "to%20do"）
• 页码从 0 开始；每页最多返回 100 个任务
• custom_fields 筛选接受 JSON 字符串数组，而非对象

常见模式

ID 解析

始终按照以下层级将名称解析为 ID：

• 工作区名称 -> team_id：调用 CLICKUP_GET_AUTHORIZED_TEAMS_WORKSPACES，并按名称匹配
• 空间名称 -> space_id：使用 team_id 调用 CLICKUP_GET_SPACES
• 文件夹名称 -> folder_id：使用 space_id 调用 CLICKUP_GET_FOLDERS
• 列表名称 -> list_id：浏览文件夹，或使用 CLICKUP_GET_FOLDERLESS_LISTS
• 任务名称 -> task_id：使用 list_id 调用 CLICKUP_GET_TASKS，并按名称匹配

分页

• CLICKUP_GET_TASKS：按页获取，page 从 0 开始，每页最多 100 个任务
• CLICKUP_GET_TASK_COMMENTS：使用 start（Unix 毫秒）和 start_id 进行基于游标的分页，每页最多 25 条
• 持续获取，直到响应返回的条目数少于页面大小

已知注意事项

ID 格式

• 工作区/团队 ID 是较大的整数
• 空间、文件夹和列表 ID 是整数
• 任务 ID 是字母数字字符串（例如 "9hz"、"abc123"）
• 用户 ID 是整数
• 评论 ID 是整数

速率限制

• ClickUp 会实施速率限制；批量创建任务可能触发 429 响应
• 如果存在 Retry-After 标头，请遵循其指示
• 批量操作时设置 notify_all=false，以减少通知量

参数注意事项

• API 中的 team_id 指工作区 ID，而非用户组
• 任务的 status 区分大小写，且因列表而异
• 日期使用 Unix 时间戳，单位为毫秒（秒数需乘以 1000）
• priority 是 1–4 的整数（1=紧急，4=低），而非字符串
• CLICKUP_CREATE_TASK_COMMENT 将 assignee 和 notify_all 标记为必需参数
• 若要清空任务描述，请向 CLICKUP_UPDATE_TASK 传入单个空格 " "

层级规则

• 子任务的父任务不能本身是子任务
• 子任务的父任务必须位于同一列表
• 列表可以不属于任何文件夹（直接位于空间中），也可以位于文件夹内
• CLICKUP_CREATE_TASK 不支持子项看板

Quick Reference

Task	Tool Slug	Key Params
List workspaces	CLICKUP_GET_AUTHORIZED_TEAMS_WORKSPACES	(none)
List spaces	CLICKUP_GET_SPACES	team_id
Get space details	CLICKUP_GET_SPACE	space_id
List folders	CLICKUP_GET_FOLDERS	space_id
Get folder details	CLICKUP_GET_FOLDER	folder_id
Create folder	CLICKUP_CREATE_FOLDER	space_id, name
Folderless lists	CLICKUP_GET_FOLDERLESS_LISTS	space_id
Get list details	CLICKUP_GET_LIST	list_id
Create task	CLICKUP_CREATE_TASK	list_id, name, status, assignees
Update task	CLICKUP_UPDATE_TASK	task_id, status, priority
Get task	CLICKUP_GET_TASK	task_id, include_subtasks
List tasks	CLICKUP_GET_TASKS	list_id, statuses, page
Delete task	CLICKUP_DELETE_TASK	task_id
Add comment	CLICKUP_CREATE_TASK_COMMENT	task_id, comment_text, assignee
List comments	CLICKUP_GET_TASK_COMMENTS	task_id, start, start_id
Update comment	CLICKUP_UPDATE_COMMENT	comment_id, comment_text, resolved
Workspace seats	CLICKUP_GET_WORKSPACE_SEATS	team_id
List user groups	CLICKUP_GET_TEAMS	team_id
Get user details	CLICKUP_GET_USER	team_id, user_id
Custom roles	CLICKUP_GET_CUSTOM_ROLES	team_id

---

Powered by Composio