clickup-mcp-full

一个 ClickUp MCP 服务器，可以在一次调用中读取整个嵌套子任务树。

它包装了 @twofeetup/clickup-mcp 而不是 fork 它，因此上游修复会随着依赖升级而到来。在该服务器之上，它添加了 get_task_tree，重写了一个可靠地误导较小模型的工具描述，并固定了一套合理的默认工具集。

为什么

上游访问子任务的唯一途径是使用 include_subtasks 的 search_tasks，它调用 GET /task/{id}?subtasks=true 并返回仅直接子任务的完整任务对象。对于一个嵌套了多层、包含五十个子任务的任务来说，这既是不完整的，也会对代理的上下文窗口造成毁灭性影响。另一种选择是每个节点发一次请求，但那样更糟。

get_task_tree 改为只遍历一次包含该任务的列表。ClickUp 的 GET /list/{id}/task?subtasks=true 返回列表中的每个任务及其 parent 指针，因此树可以在本地重新组装：无论深度或宽度如何，总共只需两个请求，输出是每个任务一行紧凑的内容。

Task tree for 86capt3b: 23 task(s) including the root.
Statuses: in progress: 3, open: 14, complete: 6
List: Q3 Delivery

86capt3b  [in progress]  Migrate billing service  <ivan>
  86captk1  [complete]  Audit current schema  <olena>
  86captk2  [in progress]  Write migration scripts  <ivan>
    86captm7  [open]  Handle partial refunds
    86captm8  [open]  Backfill historical rows
  86captk3  [open]  Cutover plan

Related MCP server: ClickUp MCP

安装

无需克隆或构建。将你的代理指向该包，它会在首次启动时获取。

Claude Code

claude mcp add clickup_full_local \
  --env CLICKUP_API_KEY=pk_your_token \
  --env CLICKUP_TEAM_ID=9012345678 \
  -- npx -y github:breckenreed/clickup-mcp-full

Claude Desktop、Cursor、Windsurf 或任何使用 mcpServers JSON 的客户端

{
  "mcpServers": {
    "clickup_full_local": {
      "command": "npx",
      "args": ["-y", "github:breckenreed/clickup-mcp-full"],
      "env": {
        "CLICKUP_API_KEY": "pk_your_token",
        "CLICKUP_TEAM_ID": "9012345678"
      }
    }
  }
}

Hermes (~/.hermes/config.yaml)

mcp_servers:
  clickup_full_local:
    command: npx
    args: ["-y", "github:breckenreed/clickup-mcp-full"]
    env:
      CLICKUP_API_KEY: "${CLICKUP_API_KEY}"
      CLICKUP_TEAM_ID: "${CLICKUP_TEAM_ID}"
    connect_timeout: 60
    keepalive_interval: 60
    idle_timeout_seconds: 1800

全局安装，如果你不想每次启动都从 GitHub 解析：

npm install -g github:breckenreed/clickup-mcp-full

然后使用 clickup-mcp-full 作为命令，不带任何参数。

凭据

ClickUp 个人令牌本身没有作用域。它代表创建它的用户，并继承该用户的权限，因此如果你想要一个不能写入的代理，请在只读的 ClickUp 账户下创建令牌，而不是依赖工具选择。

工具

上游还提供了 attach_file_to_task，它可以将本地文件上传到 ClickUp。这里默认关闭：对于在没有逐操作确认的情况下运行的代理，它会把代理读取到的任何提示注入变成数据外泄路径。如果你需要，请有意启用它：

ENABLED_TOOLS=get_workspace_hierarchy,search_tasks,manage_task,task_comments,get_container,manage_container,find_members,operate_tags,task_time_tracking,attach_file_to_task

选项

在共享工作区中提高 REQUEST_SPACING。 默认允许每秒约十个请求，而 ClickUp 在大多数套餐中每个令牌的限制约为每分钟 100 个。该限制是针对令牌而不是工具计算的，因此耗尽其额度的代理也会破坏同一令牌下运行的所有其他集成。700 可让你保持在每分钟 100 次的上限以下。

行为说明

另一个列表中的子任务。 树是通过遍历包含根任务的列表来构建的。如果你的工作区将子任务放在与其父任务不同的列表中，这些子任务将不会出现，服务器会回退到任务端点报告的直接子任务。如果你遇到这种情况并且它很重要，请提交 issue。

search_tasks 描述。 上游描述（“Works 3 ways”）会导致较小的模型将像 86capt3b 这样的普通 ID 放入 customTaskId，而该字段仅用于像 DEV-123 这样的带前缀 ID。这样的调用会落入工作区搜索分支并失败，报错“At least one filter parameter is required”，这个错误指错了问题，之后模型往往会发明过滤器而不是修复该字段。此服务器用模型实际需要的单一规则替换了该描述。

在 Docker 中使用绑定挂载的主目录运行。 如果你的代理使用指向绑定挂载的 HOME 启动 MCP 服务器，npx 会在每次连接时跨该挂载重建其包缓存，这可能需要几分钟并超时。改为在镜像内全局安装，并将 command: 指向二进制文件。

故障排除

检查服务器是否启动并列出其工具：

CLICKUP_API_KEY=pk_... CLICKUP_TEAM_ID=... npx -y github:breckenreed/clickup-mcp-full --help

Missing required environment 表示变量未到达进程：大多数客户端要求它们位于服务器自己的 env 块中，而不是你的 shell 中。

任何工具返回 401 表示令牌错误或已被撤销。429 表示你正在达到速率限制，因此请提高 REQUEST_SPACING。

许可证

MIT，与其包装的上游服务器相同。@twofeetup/clickup-mcp 是 @taazkareem/clickup-mcp-server 付费树（pre-paid tree）的 MIT 许可社区延续。