clickup-mcp

clickup-mcp

已停止维护。 CAVORT 已停用 ClickUp（2026-10-18，已完成切换至 Console）。此服务将保持现状，不再开发。

轻量级 ClickUp MCP 服务，专注于任务管理。提供 40 个工具，采用令牌优化型响应——自动将 API 响应从数千个字符精简至必要内容。

为什么选择此服务？

ClickUp 的 API 会返回极其冗长的 JSON。此服务会将其精简：

响应	精简前	精简后	缩减比例
clickup_whoami	约 3,500 个字符	约 160 个字符	95%
clickup_create_comment	约 1,500 个字符	约 38 个字符	97%

令牌更少 = 响应更快、成本更低、为 AI 留出更多上下文。

安装

npm install -g @cavort-it-systems/clickup-mcp

或直接运行：

npx @cavort-it-systems/clickup-mcp

配置

Claude Code CLI

claude mcp add clickup -e CLICKUP_API_TOKEN=your-token -- npx @cavort-it-systems/clickup-mcp

Claude Desktop / 手动配置

将以下内容添加到 MCP 配置中（~/.claude.json 或 Claude Desktop 设置）：

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["@cavort-it-systems/clickup-mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "your-token"
      }
    }
  }
}

从源代码构建

git clone https://github.com/cvrt-jh/clickup-mcp.git
cd clickup-mcp
pnpm install && pnpm build

然后使用构建后的路径进行配置：

claude mcp add clickup -e CLICKUP_API_TOKEN=your-token -- node /path/to/clickup-mcp/build/index.js

自定义任务 ID

所有接受 task_id 的工具也接受自定义 ID（DEV-1217），而不仅限于 内部 ID（86caqr85m）。服务会自行添加 custom_task_ids=true&team_id=...。 工作区 ID 取自 CLICKUP_TEAM_ID；如果未设置，则使用令牌所属的唯一 工作区（仅查询一次）。如果令牌可访问多个工作区，则必须设置 CLICKUP_TEAM_ID。

获取 API 令牌

1. 前往 ClickUp Settings > Apps
2. 生成 Personal API Token
3. 将其设置为 CLICKUP_API_TOKEN

响应精简

所有响应都会自动精简，以节省令牌。ClickUp API 会返回极其冗长的 JSON——此服务会将其精简为重要内容。

clickup_whoami——从约 3,500 个字符精简至约 160 个：

// Before (ClickUp API raw)
{"user":{"id":12345678,"username":"Jane Doe","email":"[email protected]","color":"#0388d1",
"profilePicture":"https://attachments.clickup.com/...","initials":"JD",
"week_start_day":1,"global_font_support":true,"timezone":"Europe/Berlin"},
"teams":{"teams":[{"id":"99999999","name":"My Workspace","color":"#40BC86",
"avatar":"https://attachments2.clickup.com/...?Expires=...&Key-Pair-Id=...&Signature=...",
"members":[{"user":{"id":11111111,"username":"Bob Smith","email":"[email protected]",
"color":"#aa2fff","profilePicture":null,"initials":"BS","role":4,"role_subtype":2,
"role_key":"guest","custom_role":null,"last_active":"...","date_joined":"...",
"date_invited":"..."},"invited_by":{"id":22222222,...},
"can_see_time_spent":true,...}, ...]}]}}

// After (slimmed)
{"id":12345678,"username":"Jane Doe","email":"[email protected]",
"timezone":"Europe/Berlin","workspaces":[{"id":"99999999",
"name":"My Workspace","member_count":4}]}

clickup_create_comment——从约 1,500 个字符精简至 38 个：

// Before
{"id":90150191300876,"hist_id":"...","date":1770053982842,
"version":{"object_type":"comment","object_id":"...","workspace_id":99999999,
"operation":"c","data":{"context":{"root_parent_type":1,"is_chat":false,
"audit_context":{"userid":12345678,"current_time":...,"route":"*"},...},...},...}}

// After
{"id":90150191300876,"date":1770053982842}

会精简的内容：

字段	所在位置	原因
features{}	空间	每个空间约有 50 行布尔标记
sharing{}、permission_level	任务	内部访问配置，没有实用价值
watchers[]	任务	通常与受分配者相同
完整用户对象	所有位置	精简为 {id, username, email}
profilePicture、initials、color	用户	视觉元数据，对大模型没有实用价值
version{} 数据块	创建评论/回复时	内部版本数据
invited_by、profileInfo	成员	邀请元数据
格式化 JSON	所有响应	紧凑的单行输出
空数组	任务	内容为空时省略 checklists、dependencies、custom_fields

工具（40 个）

导航（7 个）

• clickup_whoami - 当前用户和工作区
• clickup_get_spaces - 工作区中的空间
• clickup_get_folders - 空间中的文件夹
• clickup_get_lists - 文件夹或空间中的列表
• clickup_get_list - 单个列表的详情
• clickup_create_list - 在文件夹或空间中创建列表
• clickup_delete_list - 删除列表（永久）

任务 CRUD（5 个）

• clickup_get_task - 按 ID 获取任务
• clickup_create_task - 创建包含所有字段的任务
• clickup_update_task - 更新任意任务字段
• clickup_get_tasks - 列出列表中的任务
• clickup_search_tasks - 搜索整个工作区中的任务

自定义字段（1 个）

• clickup_set_custom_field - 设置自定义字段值

标签（6 个）

• clickup_get_space_tags - 列出空间标签
• clickup_create_space_tag - 创建标签
• clickup_edit_space_tag - 编辑标签
• clickup_delete_space_tag - 删除标签
• clickup_add_tag_to_task - 为任务添加标签
• clickup_remove_tag_from_task - 从任务中移除标签

检查清单（6）

• clickup_create_checklist - 创建检查清单
• clickup_edit_checklist - 编辑检查清单
• clickup_delete_checklist - 删除检查清单
• clickup_create_checklist_item - 添加条目
• clickup_edit_checklist_item - 编辑条目
• clickup_delete_checklist_item - 删除条目

依赖关系（4）

• clickup_add_dependency - 添加依赖关系
• clickup_delete_dependency - 移除依赖关系
• clickup_add_task_link - 链接任务
• clickup_delete_task_link - 取消链接任务

评论（5）

• clickup_create_comment - 添加评论
• clickup_get_comments - 获取评论
• clickup_update_comment - 编辑/解决评论
• clickup_create_reply - 线程回复
• clickup_get_replies - 获取回复

删除任务（1）

• clickup_delete_task - 删除任务

多列表归属（2）

• clickup_add_task_to_list - 将任务添加到额外列表（多列表归属）
• clickup_remove_task_from_list - 从额外列表中移除任务

这些操作不会移动任务。 ClickUp v2 API 没有列表间移动端点。经核实，2026-08-12 的实时 API 中：POST /list/{list}/task/{task} 会添加一个次要位置，并保持主列表不变；而在 PUT /task/{id} 中使用 list_id 会返回 HTTP 200，但被静默忽略。要真正移动任务并保留其自定义 ID 和历史记录，请使用 ClickUp 网页 UI（右键 -> 移动）。多列表归属还需要付费的 Tasks-in-Multiple-Lists 功能。

附件（1）

• clickup_upload_attachment - 将本地文件（屏幕截图、PDF）上传到任务

工作区成员（2）

• clickup_get_workspace_members - 获取所有工作区成员
• clickup_get_list_members - 获取特定列表的成员

架构

src/
  index.ts          # Entry: McpServer + StdioServerTransport
  client.ts         # ClickUp API v2 fetch wrapper
  types.ts          # Shared Zod schemas + jsonResult helper
  slim.ts           # Response slimming transformers
  tools/
    navigation.ts   # 7 tools
    tasks.ts        # 9 tools (CRUD + custom fields + delete + multi-list)
    tags.ts         # 6 tools
    checklists.ts   # 6 tools
    dependencies.ts # 4 tools
    comments.ts     # 5 tools
    members.ts      # 2 tools
    attachments.ts  # 1 tool (multipart upload)

许可证

MIT