Clickup MCP

🚀 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 令牌

1. 前往 ClickUp 设置 > 应用程序。
2. 生成个人 API 令牌。
3. 将其设置为 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 个工作区成员工具

🔧 技术细节

响应精简规则

📄 许可证

本项目采用 MIT 许可证。