JinDaGe - clickup-mcp MCP Details

article

README

🚀 clickup-mcp

轻量级的 ClickUp MCP 服务器，专注于任务管理。拥有 37 个工具，具备 令牌优化响应 功能 —— API 响应会自动从数千个字符精简为关键内容。

🚀 快速开始

本项目是一个专注于任务管理的轻量级 ClickUp MCP 服务器，能将 ClickUp API 返回的冗长 JSON 响应精简，节省令牌，实现更快响应、更低成本，并为 AI 提供更多上下文。

✨ 主要特性

响应精简：ClickUp 的 API 返回的 JSON 内容极为冗长，本服务器对其进行精简。例如，clickup_whoami 响应从约 3500 个字符精简到约 160 个字符，缩减了 95%；clickup_create_comment 响应从约 1500 个字符精简到约 38 个字符，缩减了 97%。
令牌优化：更少的令牌意味着更快的响应速度、更低的成本，以及为 AI 提供更多的上下文。
丰富工具：提供 37 个工具，涵盖导航、任务 CRUD、自定义字段、标签、清单、依赖项、评论、删除任务和工作区成员等功能。

📦 安装指南

使用 npm 全局安装

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

直接运行

npx @cavort-it-systems/clickup-mcp

从源代码安装

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

💻 使用示例

基础用法

配置 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"
      }
    }
  }
}

从源代码配置

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

高级用法

获取 API 令牌

前往 ClickUp 设置 > 应用程序。
生成个人 API 令牌。
将其设置为 CLICKUP_API_TOKEN。

响应精简示例

clickup_whoami —— 从约 3500 个字符精简到约 160 个字符：

// Before (ClickUp API raw)
{"user":{"id":12345678,"username":"Jane Doe","email":"jane@example.com","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":"bob@example.com",
"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":"jane@example.com",
"timezone":"Europe/Berlin","workspaces":[{"id":"99999999",
"name":"My Workspace","member_count":4}]}

clickup_create_comment —— 从约 1500 个字符精简到 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}

📚 详细文档

工具列表

导航（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_get_workspace_members - 获取工作区的所有成员
clickup_get_list_members - 获取列表特定的成员

架构

src/
  index.ts          # 入口文件：McpServer + StdioServerTransport
  client.ts         # ClickUp API v2 封装
  types.ts          # 共享的 Zod 模式和 jsonResult 辅助函数
  slim.ts           # 响应精简转换器
  tools/
    navigation.ts   # 7 个导航工具
    tasks.ts        # 7 个任务工具（CRUD + 自定义字段 + 删除）
    tags.ts         # 6 个标签工具
    checklists.ts   # 6 个清单工具
    dependencies.ts # 4 个依赖项工具
    comments.ts     # 5 个评论工具
    members.ts      # 2 个工作区成员工具

🔧 技术细节

响应精简规则

| 字段 | 位置 | 原因 | |-------|-------|-----| | features{} | 空间 | 每个空间约有 50 行布尔标志 | | sharing{}, permission_level | 任务 | 内部访问配置，对大语言模型无用 | | watchers[] | 任务 | 通常与分配人相同 | | 完整用户对象 | 各处 | 简化为 {id, username, email} | | profilePicture, initials, color | 用户 | 视觉元数据，对大语言模型无用 | | version{} 数据块 | 评论/回复创建 | 内部版本控制数据 | | invited_by, profileInfo | 成员 | 邀请元数据 | | 美化后的 JSON | 所有响应 | 紧凑的单行输出 | | 空数组 | 任务 | 当 checklists、dependencies、custom_fields 为空时省略 |

📄 许可证

本项目采用 MIT 许可证。

clickup-mcp