ClickUp MCP Server

一个用于 ClickUp 的 Model Context Protocol 服务器，围绕两个理念构建：

一切皆用人名。 find(scope: "Cavalry/Findings", assignee: "me", due: "overdue") —— 无需 ID，也无需遍历树来发现它们。无法解析的名称会引发错误，并列出有效选项，因为一个自信的空结果比失败更糟糕。

你决定它能做什么。 四个能力配置文件，在每个出站请求上强制执行。将 agent 配置文件交给无人值守的代理，它可以创建任务和评论，但不能修改或删除任何已存在的内容。

18 个工具，354 个测试。版本 4.3.0 —— 参见 CHANGELOG.md。一个经过大量翻新的 nsxdavid/clickup-mcp-server 分支。

状态： 4.x 是新的。它已经经历了五轮对抗性红队测试，但尚未在生产环境中运行。之前的 3.x 系列仍在此仓库中发布，并且仍然是参考部署所运行的版本 —— 参见 运行 3.x。

快速开始

从 ClickUp → 设置 → 应用 → API 令牌 获取一个令牌（以 pk_ 开头）。工作区会自动发现 —— 无需其他配置。

无需安装：

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "github:benthesoundguy/clickup-mcp-server"],
      "env": { "CLICKUP_API_TOKEN": "pk_your_token_here" }
    }
  }
}

或者从克隆开始，如果你打算更改任何内容，这是你想要的：

git clone https://github.com/benthesoundguy/clickup-mcp-server
cd clickup-mcp-server
npm install          # builds automatically
npm run check        # verifies the token and connects — do this before wiring up a client

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/absolute/path/to/clickup-mcp-server/build/v4/index.js"],
      "env": { "CLICKUP_API_TOKEN": "pk_your_token_here" }
    }
  }
}

该块放在哪里

上述形状在 Claude Desktop、Claude Code、Cursor、Cline 和 Windsurf 中可直接使用 —— 它们都使用 mcpServers 键。两个客户端有所不同：

• VS Code (.vscode/mcp.json) 使用 servers 而不是 mcpServers。内部形状相同。直接复制 Cursor 配置是最常见的设置错误。

• Zed (settings.json) 使用 context_servers，并嵌套命令：

  { "context_servers": { "clickup": { "command": { "path": "node", "args": ["/path/to/build/v4/index.js"] } } } }

Claude Code 可以完全跳过该文件：

claude mcp add clickup --env CLICKUP_API_TOKEN=pk_... -- npx -y github:benthesoundguy/clickup-mcp-server

将令牌放入文件

如果你不想将令牌粘贴到客户端配置中 —— 桌面应用会重写这些文件，并可能保留过时的副本 —— 将其放在安装目录旁边的 .env 中，并完全省略 env 块：

echo 'CLICKUP_API_TOKEN=pk_your_token_here' > .env

服务器按顺序查找 <cwd>/.env、<install>/.env 和 <install>/../.env，并在启动时说明使用了哪一个。文件中的令牌优先于环境变量，因此在一个地方轮换它实际上会生效。其他所有设置则相反 —— 客户端配置中的显式值始终获胜，因此杂散的 .env 永远无法扩大 MCP_PROFILE。在服务器上设置 MCP_STRICT_ENV=1 可完全关闭整个查找。

当它不起作用时

npm run check          # from a clone
node build/v4/index.js --check

这会打印服务器解析的每个输入 —— 它找到了哪个 .env 以及应用了什么，令牌是否存在且形状正确，活动配置文件和工具数量，Node 版本和构建戳 —— 然后实际连接到 ClickUp 并报告你是谁以及你的速率预算。它从不打印令牌，因此输出可以安全地粘贴到问题中。

如果令牌缺失，服务器不会在 stdio 模式下静默死亡。它会启动，注册其工具，并且每次调用都会回答出了什么问题以及如何修复，因此问题会出现在你的对话中，而不是你必须去查找的日志文件中。（在 HTTP 模式下，它仍然以 1 退出 —— 无人值守的部署应该大声失败。）

Related MCP server: ClickUp MCP Server

能力配置文件

一个二进制文件，四个配置文件，通过 MCP_PROFILE 选择。安装一次，并为每个配置文件添加一个客户端条目，启用给定代理应具有的任何一个。

模式成本是工具定义在每次请求中消耗的模型上下文，在任何工作发生之前。作为比较，3.x 为 88 个工具花费约 18,600 个令牌。

agent 是有趣的一个。 它可以添加，但永远不能修改或销毁，因此无人值守的代理最坏的情况是创建你可以删除的杂乱。该保证在三层中强制执行，只有第三层是安全边界：

1. 工具过滤 —— 哪些工具出现 (上下文成本 + 工具选择)

2. 操作过滤 —— 工具宣传哪些操作 (上下文成本 + 诚实)

3. 写入策略 —— 在每个出站请求上检查的允许列表，包括上传 ← 保证

第 1 层和第 2 层依赖于每个工具被每个未来的贡献者正确标记。第 3 层不依赖：它检查实际请求在出去的路上，因此错误标记的工具、重构或明年添加的端点无法扩大配置文件。测试套件通过直接使用 agent 上下文调用仅 core 的处理程序来证明这一点 —— 完全绕过第 1 层和第 2 层 —— 并断言没有任何内容到达线路。

看起来是添加性的但故意从 agent 中排除的事物：附加标签、设置自定义字段和添加依赖项都会修改现有任务；创建 webhook 开始将你的数据流式传输到外部端点。仅追加和安全不是同一个属性。

为什么默认是 core 而不是 full

full 授予成员资格管理 —— 邀请用户会消耗付费席位，移除用户会改变真实人员的访问权限 —— 加上 webhook，后者将工作区数据发送到外部。这些都不是第一次连接的目的，而且没有人更改的默认值必须是安全的。当你想要管理时，按名称请求它；在你这样做之前，拒绝会准确告诉你如何做。

附件和文件系统

attach 从服务器运行的机器上读取文件。这是一个写入策略无法看到的资源 —— 它检查 URL，而文件读取没有 URL —— 因此它由 CLICKUP_ATTACH_ROOT 单独管理：

• 设置 → 读取限制在该目录内。包含性检查是针对文件的真实路径，在解析 .. 和每个符号链接之后。

• 未设置 → core 和 full 可以读取进程可以读取的任何文件。在 agent 下，attach 根本不提供（12 个工具而不是 13 个），因为没有安全的默认根：工作目录通常是项目目录，而 .env 就在那里。

配置错误的根在启动时是致命的，而不是被忽略 —— 一个静默不存在的边界比没有更糟糕。

工具

工具在合理的地方缩小而不是消失：在 read 下，comment 只显示其读取参数，checklist 只宣传 list，因此模式告诉连接可以做什么的真相，而不是宣传会被拒绝的操作。

一切遵循的规则

永远不要返回自信的错误答案。 ClickUp 很容易出错，因为它用愉快的废话回答坏输入：

因此，此服务器解析名称并在歧义时引发错误（“Findings”匹配四个列表是一个错误，列出所有四个，而不是抛硬币）；当过滤器值无法解析时引发而不是返回空；在客户端验证枚举，针对列表实际接受的内容；验证它无法信任的写入，通过读回对象；并且从不夸大计数 —— 停止分页的查询报告 100+ 匹配，任何客户端过滤器报告它实际扫描了多少。

错误说明什么失败了、为什么以及下一步该做什么，并列出有效选项。

环境变量

远程模式（Claude 网页 + 移动端，以及任何 HTTP 客户端）

服务器支持可流式 HTTP，并接受三种独立的凭据。任何一种凭据即可验证请求；它们设计为共存，因为不同客户端可能提供不同的凭据。

MCP_TRANSPORT=http MCP_AUTH_TOKEN=$(openssl rand -hex 24) \
MCP_PROFILE=core CLICKUP_API_TOKEN=... node build/v4/index.js

GET /health 是一个无需认证的探针，报告版本、活动配置文件、工具数量和附件根目录。

OAuth（托管客户端所需）

此服务器不需要是 OAuth 提供方，也确实不是。 根据 2025-06-18 MCP 规范，MCP 服务器是资源服务器：它指定其信任的授权服务器，并验证该服务器签发的令牌。登录、同意和令牌签发属于你的 IdP——Cloudflare Access、WorkOS、Auth0、Descope、Stytch、Keycloak，以及任何支持 OIDC 发现的服务。

MCP_TRANSPORT=http \
MCP_PUBLIC_URL=https://mcp.example.com \
MCP_OAUTH_ISSUER=https://your-idp.example.com \
CLICKUP_API_TOKEN=pk_... node build/v4/index.js

这就是全部配置。服务器随后：

• 在 /.well-known/oauth-protected-resource 提供 RFC 9728 受保护资源元数据，无需认证即可命名你的签发者；

• 对未认证请求返回 401，并附上指向该文档的 WWW-Authenticate 头，客户端据此发现登录位置；

• 通过 /.well-known/openid-configuration（或 RFC 8414）发现签发者的签名密钥，或在你设置时使用 MCP_OAUTH_JWKS_URL；

• 验证每个令牌：固定使用 RS256，签名对照签发者的 JWKS，检查 exp、nbf、iss，以及 aud——令牌必须命名此服务器。

最后一项检查才是关键。没有它，你的 IdP 为其他服务签发的令牌就可能在此处被重放。这就是为什么 MCP_PUBLIC_URL 是必需而非推断的：预期的受众绝不能来自请求，因为 Host 头由调用方设置。

一旦配置了签发者，MCP_AUTH_TOKEN 就变为可选——纯 OAuth 部署不需要一个从未使用的共享密码。

关于动态客户端注册的说明。 2026-07-28 规范弃用了 DCR，改用客户端 ID 元数据文档。该变更落在授权服务器和客户端上；资源服务器无论哪种方式都不受影响，这也是委托而非自行实现 AS 的一个充分理由。

claude.ai 连接器注意事项

Claude 的自定义连接器 UI 仅接受 OAuth 字段——授权 URL、令牌 URL、客户端 ID、客户端密钥。没有用于静态 bearer token 或自定义头的字段（#112、#411）。因此：

• 配置了 OAuth 时，将其作为普通自定义连接器连接。这是预期路径。

• 未配置 OAuth 时，唯一途径是 URL 中的令牌形式 /mcp/<token>，通过 MCP_ALLOW_TOKEN_IN_PATH=1 启用。它有效，但会将凭据放在代理会记录的 URL 中，这也是严格模式拒绝它的原因。将其视为变通方案，而非部署方案。

Cloudflare Access（可选的第三种认证模式）

设置 CF_ACCESS_TEAM_DOMAIN 和 CF_ACCESS_AUD 后，服务器会验证 Access 在每个转发的请求上放置的 Cf-Access-Jwt-Assertion 头：RS256 对照团队 JWKS，外加 exp、iss 和 aud。两种 Access 流程都通过同一条路径验证——浏览器登录携带 email，服务令牌携带 common_name。

这是纵深防御。未经 Access 到达源站的请求——隧道配置错误、第二个入口、主机网络上的某些东西——无法冒充 Access 认证的调用方。它失败即关闭：alg 固定为 RS256（因此拒绝 alg: none 和 HS256 混淆），无法访问的 JWKS 会拒绝而非绕过，且 JWKS URL 来自配置，绝不来自令牌。

Bearer 认证继续有效。 请求由有效的 Access JWT 或有效的 bearer token 授权，因此支持头的代理无需任何更改。

源站不提供 /.well-known/oauth-*——启用托管 OAuth 后，Access 是授权服务器，并在边缘提供发现服务。

严格模式（MCP_STRICT_ENV=1）

适用于无人值守部署的姿态。机密必须来自环境，服务器绝不自行生成或持久化凭据，并且在配置错误时以 1 退出并给出可操作的消息，而不是在配置错误的情况下启动。它还拒绝 URL 路径中的令牌形式，因为该形式会将凭据写入代理访问日志。

这一点很重要，因为 .env 文件查找有意优先于 process.env——桌面主机在退出时会从内存重写自己的配置文件，因此文件必须在那里胜出。在服务器上，该优先级是相反的：工作目录中一个多余的 .env 会静默地优先于 systemd 单元。严格模式会关闭该查找。

完整配方见 deploy/DEPLOY.md：VPS 设置脚本、加固的 systemd 单元、Cloudflare Tunnel，以及将其连接到 Claude。

从 3.x 升级

工具名称完全不同——4.x 是重写，而非重命名。任何硬编码 3.x 工具名称的内容（保存的提示、代理指令、脚本）都需要更新。

映射关系大多是多对一：

未迁移： project_intelligence（八份本地分析报告）和 reminders_create。状态管理——创建、重命名、重新排序状态——也未迁移；meta 读取状态但不更改状态。如果你需要其中任何一项，请运行 3.x。

运行 3.x

3.x 仍从此仓库构建和发布：

npm run start:v3       # via the package script
node build/index.js    # the 3.x entry point directly

将 MCP 客户端指向 build/index.js 而不是 build/v4/index.js，即可继续使用。

deploy/ 中的参考 systemd 单元仍有意固定为 3.x，因为运行中的服务不应因包默认值在其下方移动而更改主版本。通过将 ExecStart 指向 build/v4/index.js 并显式设置 MCP_PROFILE 来迁移它。

已知的 ClickUp API 限制

这里不是 bug——API 确实缺少这些功能，此服务器会报告限制，而不是绕过它。

• 任务无法在列表之间移动。 在没有 "Tasks in Multiple Lists" ClickApp 的情况下，POST /list/{dest}/task/{id} 返回 200 {} 但不执行任何操作；带 list_id 的 PUT 会被静默忽略；/move 返回 404。update 的移动路径会重新读取任务，然后明确报错，而不是报告一次未发生的移动。

• 附件没有列表端点 — task 从任务对象上读取附件。上传仅支持 multipart 格式，上限为 25MB。

• Docs 无法重命名或删除，页面也无法删除。

• 自定义字段定义 可以列出和创建，但不能编辑或删除。

• 日期自定义字段要求 Unix 毫秒时间戳；对于这些字段，ClickUp 会拒绝 YYYY-MM-DD 格式。任务的 due_date/start_date 两种格式都接受，并在此处进行转换。

• 状态和标签名称以小写形式存储；此处的匹配全程不区分大小写。

• 列表总是覆盖其空间的状态，因此"哪些状态有效"是一个因列表而异的问题。meta 会按列表回答这个问题。

• ClickUp 对无效枚举返回 HTTP 500，因此枚举在发送前会在客户端进行验证。

• 速率限制大约为 每个 token 每分钟 100 次请求，所有使用该 token 的操作共享此限制。whoami 报告实时预算；服务器会根据 x-ratelimit-* 请求头自行调整节奏。

Webhook 接收器（可选）

无需外部基础设施即可处理 ClickUp webhook 事件：

WEBHOOK_PORT=3001 WEBHOOK_SECRET=your_secret node build/webhook-receiver/index.js

• 对原始请求体进行 HMAC-SHA256 验证；配置了密钥后，未签名的请求将被拒绝

• 结构化事件解析 — 类型、对象、操作、变更、用户、时间戳

• 可选转发到回调 URL（WEBHOOK_FORWARD_URL）

• 纯 Node.js http，零额外依赖

开发

npm install
npm run build
npm test          # 354 tests, mocked HTTP — no token needed
npm run smoke     # live CRUD walk (needs CLICKUP_API_TOKEN; creates and
                  # deletes its own sandbox in your workspace)

4.x 的架构说明位于 src/v4/README.md；设计原理和测量数据在 V4-PLAN.md 中。

调试一个"不起作用"的修复

调用 whoami。它会报告正在运行的构建的版本和戳记。MCP 宿主会在会话启动时生成自己的服务器进程并保持运行，因此重新构建不会影响到已经运行的会话 — 如果戳记早于你的更改，请重启宿主应用。在该工具出现之前，这曾导致多个幽灵 bug 报告。

许可证

MIT — 参见 LICENSE。由 David Whatley 的 nsxdavid/clickup-mcp-server 派生而来。