clickup-mcp

ClickUp MCP 服务器，适用于 Claude — 将 ClickUp 任务、空间、文件夹、列表和评论作为 MCP 工具暴露。

技术栈： Python 3.12 + uv + FastMCP (Starlette/FastAPI)

快速开始

# Install dependencies
cd D:\leo\mcp-server\clickup-mcp
uv sync

# Run in stdio mode (for Claude Desktop)
$env:CLICKUP_API_TOKEN="pk_xxxxx"
uv run clickup-mcp

Related MCP server: Clickup Universal MCP Server

配置

将 .env.example 复制为 .env 并填写你的值：

获取你的 API 令牌：ClickUp → 设置 → 应用 → API 令牌

Claude Desktop 设置

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "clickup": {
      "command": "uv",
      "args": ["run", "--directory", "D:/leo/mcp-server/clickup-mcp", "clickup-mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_xxxxx"
      }
    }
  }
}

传输模式

stdio (Claude Desktop / CLI)

$env:CLICKUP_API_TOKEN="pk_xxxxx"
uv run clickup-mcp

HTTP — 单租户

$env:CLICKUP_API_TOKEN="pk_xxxxx"
$env:MCP_TRANSPORT="http"
$env:MCP_HTTP_PORT="8080"
uv run clickup-mcp

HTTP — 网关 / 多租户

$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="gateway"
uv run clickup-mcp
# Each request must include: X-Clickup-Token: pk_xxxxx

可用工具 (28 个)

查找人员的 ClickUp 用户 ID

使用 clickup_list_members。ClickUp 的原生 GET /team 响应嵌入了每个团队的完整成员列表 (teams[].members[].user.{id,username,email})，但 clickup_get_workspaces 为了保持响应小巧而将其剥离，因此它不是查找人员的地方。clickup_list_members 读取相同的底层端点，并将成员列表投影为扁平、专用的形状 (id/username/email/team_id/role)，这样调用者就不必自己从完整的工作区/团队对象中挖掘出来。clickup_list_tasks_for_person 在内部使用相同的底层查找来将 email 解析为 user_id。

已知差距：ClickUp 的团队成员对象没有可靠的“该成员是否已停用”字段 — clickup_list_members 不返回 active 字段，因为没有任何真实数据可以支持它 (原始对象上存在的唯一 status 字段 invited_by.status 描述的是邀请者，而不是成员)。

clickup_search_tasks 已经返回 status.type

与此处的所有其他读取工具一样，clickup_search_tasks 和 clickup_get_task 会原封不动地传递 ClickUp 的原始任务对象 — 包括 status 对象的 type 字段 (open / custom / closed / done)，这是判断自定义命名状态是否算作“完成”的唯一可靠方法。无需修改代码即可实现；它本来就在那里。clickup_list_tasks_for_person 为方便起见，在每个返回的任务上将其显式显示为 status_type。

在此 ClickUp 工作区中 EOS Rocks 的表示方式

已于 2026-08-18 通过直接检查真实 rock 任务的字段确认 (非猜测)：Rocks 是在一个名称为 "Rocks" 的列表中的常规 ClickUp 任务 (位于空间 "Company" > 文件夹 "EOS Traction" 下)，每个任务都带有专用自定义字段：Quarter (下拉菜单，"Q1 2024".."Q4 2026")、Rocks Status (On Hold / Off Track / On Track / Completed / Blocked / At Risk)、Rock Type (Company / Individual / Departmental / Team Rock)、Department，以及通过 Progress (手动) 或 Progress % (自动，清单汇总) 表示的进度。这既不是 ClickUp Goals API，也不是没有元数据的纯任务列表 — 而是任务加自定义字段。

clickup_list_rocks_for_org 发现每个命名为 "Rocks" 的列表 (按名称，而非硬编码的 ID，以防空间/文件夹被重新组织)，读取这些字段，并将其规范化：

• quarter：ClickUp 的 "Q3 2026" 标签被转换为 2026-Q3 (以及反向转换，用于 quarter 输入过滤器)。

• status：ClickUp 的 6 个原始选项被映射为 5 值约定 (on_track/off_track/done/missed/open) — 请参阅 rocks.py 中的 _STATUS_MAP 注释以了解确切映射以及为何永远不会发出 missed (ClickUp 的数据中没有内容区分“耗尽时间”和通用“偏离轨道”；从过期的 due_date 推导出来将是一个未经确认的业务逻辑假设，因此此处不这样做)。

• measurable：此列表上不存在专用字段。回退到任务描述；如果该描述也为空，则为 null (从不虚构)。

• weekly_status：在任何地方都找不到结构化来源 (不是自定义字段，也不是从评论派生的) — 始终返回为 []。如果该组织开始以其他方式在 ClickUp 中跟踪此信息，请重新审视。

附件和图片

ClickUp 的 REST API 无法直接将文件附加到评论 — 只能附加到任务 (POST /task/{task_id}/attachment，这就是 clickup_attach_task_file 所包装的)。也没有删除/更新附件的端点；重新上传会添加一个新附件，而不是替换旧附件，删除附件需要 ClickUp 网页/桌面应用程序。通过检查 ClickUp 自己的官方 MCP 服务器的工具描述也确认了这一点 — 相同的拆分 (一个不支持附件的 Create Task Comment 工具，以及一个单独的 Attach File to Task 工具)。

要使图片内联显示在评论中，底层技巧是：先将文件上传到任务，然后在评论文本中使用 Markdown 图片语法引用文件响应中返回的 URL — ClickUp 的评论渲染器会将其内联为真实图片，而不仅仅是一个链接。clickup_create_comment_with_image 一次性完成两个步骤：

clickup_create_comment_with_image(task_id, file_content_base64, filename)
# internally:
#   1. POST /task/{task_id}/attachment  -> {"url": "...", ...}
#   2. POST /task/{task_id}/comment     comment_text = "![filename](url)"

若要手动执行此操作 (例如，在图片周围添加其他文本)，请自行调用这两个工具：

1. result = clickup_attach_task_file(task_id, file_content_base64, filename)
   -> result["url"] is the uploaded file's URL

2. clickup_create_task_comment(
     task_id,
     comment_text=f"![{filename}]({result['url']})"
   )

API 参考

• ClickUp API v2 文档

• 创建任务附件