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 許可證。