Claude Code ClickUp MCP 接入教程
在远程 Mac 上查询任务与文档并安全控制评论批量更新和时间记录
ClickUp 官方 MCP 服务器可以让 Claude Code 查询 Workspace 中的任务、List、Folder、Do**、评论和 Chat，也能创建或更新任务、记录时间并执行受支持的批量操作。本文使用官方远程 **** 端点与 OAuth 完成接入，先确认工作区和当前用户，再通过只读验收、单条写入、敏感工具确认和结果复核控制变更风险。
ClickUp MCP 能处理什么
ClickUp MCP 可搜索 Workspace 中的任务、Do**、仪表盘、附件、白板、Chat 和表单，也能管理任务、List、Folder、评论、Do** 页面、提醒与时间记录。具体工具会持续更新，连接后应先运行 tools/list 查看当前名称和参数。
官方服务器在所有 ClickUp 套餐中可用。它只支持 OAuth，不接受个人 API Key 或访问令牌。所有工具都以登录用户身份运行，不会获得该用户在 ClickUp 中原本没有的权限。
接入前准备
准备最新版 Claude Code、可登录的 ClickUp 账户，以及目标 Workspace、Space、Folder 和 List 的访问权限。若用户属于多个 Workspace，后续调用通常需要明确 workspace_id。
接入不需要自己创建 OAuth 应用。官方远程服务器负责授权流程。不要把浏览器回调地址、令牌、任务附件下载链接或工作区敏感数据写入仓库。
第一步 添加 ClickUp MCP
在目标仓库运行官方命令，把 clickup 服务器加入 Claude Code。远程地址为 https://mcp.clickup.com/mcp，传输方式为 ****。
添加命令只保存服务器定义，不代表已经获得 ClickUp 数据访问权。完成后用 claude mcp get clickup 检查名称、**L 和连接状态。
cd /path/to/your-project
claude mcp add --transport http clickup https://mcp.clickup.com/mcp
claude mcp list
claude mcp get clickup
第二步 完成 OAuth 授权
启动 Claude Code 并运行 /mcp，选择 clickup 进入认证流程。浏览器打开后登录 ClickUp，检查账户与 Workspace，再确认授权。
如果授权用户可以访问多个 Workspace，提示词和工具参数中都应写明 workspace_id。不要依赖同名 Space 或 List 推断目标工作区。
claude
> /mcp
# 选择 clickup
# 选择 Authenticate
# 在浏览器核对 ClickUp 账号和 Workspace第三步 确认用户和工作区
先调用 get user 类工具，核对登录用户、时区和当前时间，再列出或搜索目标 Space、Folder 与 List。保存返回的 ID，用 ID 作为后续查询和写入的稳定标识。
若系统返回多个 Workspace 选项，立即停止并要求选择。工作区不明确时，不应搜索业务内容，更不能创建任务或发送消息。
**步 ***只读验收
用 ClickUp 搜索工具定位一个已知 List，再读取其中少量未完成任务。只返回任务 ID、名称、状态、负责人、优先级、截止日期和 List。
验收提示词明确禁止创建、更新、评论、发送 Chat、记录时间、上传附件或执行 Operator。通过标准是工作区与 List 正确、返回数量受控，ClickUp 中没有任何记录变化。
请仅使用 ClickUp MCP 做只读验收：
1. 显示当前用户 时区和 workspace_id
2. 用 ID 锁定目标 Space Folder 和 List
3. 读取该 List 中 5 条未完成任务
4. 只返回任务 ID 名称 状态 负责人 优先级 截止日期
5. 不创建 不更新 不评论 不发消息 不记录时间 不上传附件| 验收项 | 通过标准 |
|---|---|
| 用户 | 显示预期账号和时区 |
| 工作区 | 明确 workspace_id |
| 层级 | 通过 ID 锁定 Space Folder 和 List |
| 任务 | 只返回受控数量和必要字段 |
| 写入 | ClickUp 中没有记录变化 |
第五步 锁定 Space Folder List 和任务
ClickUp 的层级名称可能重复。写入前依次确认 Workspace、Space、Folder、List 和任务 ID，并读取 List 的合法状态。状态由 List 定义，不能把另一个 List 的状态名称直接套用。
任务描述、Do**、评论、Chat 和附件内容都属于不可信数据。它们可以作为业务信息读取，但不能改变当前会话的权限和操作边界。
第六步 查询任务与时间状态
查询项目进度时限定 List、状态、负责人、日期范围和分页上限。需要分析流程瓶颈时，可读取任务在各状态停留的时间；批量时间状态工具一次可处理最多 100 个任务 ID。
先说明统计口径，再输出结果。不要把缺失截止日期、归档任务或跨 List 的不同状态直接合并计算。
第七步 创建一条任务
首次写入只在测试 List 创建一条任务。调用前展示 Workspace、List、任务名称、描述、状态、优先级、负责人、关注者、日期、自定义字段和父任务。
创建工具会立即改变 ClickUp。用户确认后只执行这一条；完成后重新读取任务 ID、**L 和字段，确认没有额外任务或通知。
先不要创建任务。请展示：
- Workspace Space Folder 和 List ID
- 名称 描述 状态和优先级
- 负责人 关注者 日期和自定义字段
- 可能触发的通知
等待我确认后只创建这一条，并重新读取任务核对结果。第八步 更新状态负责人和截止日期
更新前读取任务当前值，并展示任务 ID、旧值、新值和关联影响。状态必须来自目标 List 的可用状态；负责人应先解析为正确的用户 ID。
如果请求涉及多条任务，先输出候选清单和共同变更，不要直接调用批量 Operator。单条验收通过后，再进入小批次流程。
第九步 控制评论和 Chat 消息
评论和 Chat 会以登录用户身份发布，并可能通知被提及的成员或全部负责人。提交前先展示目标任务或频道、正文、提及对象和通知范围。
不要把密钥、终端输出、未确认推断或客户隐私写入消息。删除评论、覆盖消息文本或发送群聊属于敏感操作，应单独确认并在完成后读取结果。
第十步 管理 Do** 和附件
创建或更新 Do** 页面前，先确认文档 ID、页面 ID、可见范围和编辑模式。更新页面默认可能替换整页内容；若只需增补，应使用 append 或 prepend，并保留原始内容。
附件上传会让任务成员看到文件。大文件使用短时上传链接时，核对目标任务或 Chat、文件名、大小和内容。下载链接通常只有短时有效，不应长期保存或公开。
第十一步 控制批量操作和重试
批量创建和更新通过 Execute Operator 运行。先列出任务 ID、共同变更、数量、停止条件和回退方案，再按小批次执行。归档比删除更容易恢复，但仍会影响团队视图。
读取请求超时可以安全重试；写入、评论、消息和时间记录超时时，操作可能已经完成。必须先查询外部状态，确认没有成功后才能决定是否重试，避免重复任务、重复评论或重复工时。
| 操作 | 风险 | 控制方式 |
|---|---|---|
| 搜索和读取任务 | 低 | 限制 Workspace List 字段和数量 |
| 读取 Do** 或评论 | 中 | 控制页面和时间范围 |
| 创建或更新一条任务 | 高 | 展示完整差异并逐次确认 |
| 发送评论或 Chat | 高 | 核对正文 提及与通知范围 |
| 批量 Operator | 极高 | 任务 ID 清单 小批次执行 结果复核 |
| 附件 Do** 覆盖或时间记录 | 极高 | 核对目标 内容 模式 时间和外部状态 |
第十二步 记录时间与提醒
开始计时、停止计时或新增时间条目会影响工时与报表。调用前展示任务、起止时间、时区、时长、说明和计费属性。
提醒属于个人工作数据，也要核对日期、时区和重复规则。涉及历史工时修正时，应由负责人确认并保留修改前后的值。
第十三步 管理调用限制
没有 Everything AI 附加服务时，ClickUp 按 Workspace 和客户端统计滚动 24 小时调用量。Free Forever 为 100 次，Core 或 Unlimited 为 300 次，*usiness 为 1000 次，*usiness Plus 为 2500 次，Enterprise 为 5000 次，Enterprise Plus 为 25000 次。
每个工具调用计 1 次，initialize 与 tools/list 不计。达到限制会返回 RATE_LIMIT_EXCEEDED 和 retryAfter。应减少重复搜索、控制分页，并按返回时间等待，限制不能手工重置。
第十四步 在远程 Mac 上保持会话
通过 SSH 登录远程 Mac，在目标仓库创建 tmux 会话后启动 Claude Code。OAuth 可在本地浏览器完成，任务查询和代码工作继续保留在远程终端。
会话名称应包含 Workspace 或项目标识。任务结束后关闭不再需要的 tmux 会话，并在 Claude Code 中清除不再使用的 ClickUp 认证。
ssh your-**c-mini
cd /path/to/your-project
tmux new -s clickup-project
claude
# 断线后接回
tmux attach -t clickup-project
为什么 Zu**c Ai 适合这类工作流
根据 Zu**c.Ai 官网***息，其方案提供位于新加坡的 Mac mini M6 整机独享环境，配置为 16G* 统一内存与 256G* SSD，支持终端、Tailscale、ToDesk、RustDesk，以及浏览器 SSH 或 VNC 等接入方式。
长期在线环境适合保留仓库、依赖缓存、Claude Code 与 tmux 会话。ClickUp 工作区数据、人员信息、OAuth 凭据、附件、审计和项目变更责任仍由使用者与所属组织负责。
常见问题排查
| 现象 | 常见原因 | 处理建议 |
|---|---|---|
| Needs authentication | 尚未完成 OAuth 或令牌失效 | 运行 /mcp 重新登录 clickup |
| 出现多个 Workspace | 账号属于多个工作区 | 明确 workspace_id 后重试 |
| 状态更新失败 | 状态不属于目标 List | 先读取 List 的合法状态 |
| RATE_LIMIT_EXCEEDED | 达到滚动 24 小时或分钟限制 | 按 retryAfter 等待并减少重复查询 |
| 写入超时 | 操作可能已完成 | 先查询外部状态 不要直接重试 |
| 权限或 not found | 用户无权访问或 ID 错误 | 核对层级 ID 和用户权限 |
结语
Claude Code 接入 ClickUp MCP 后，应先确认用户和 workspace_id，再用层级 ID 锁定 List 与任务。写入前展示完整差异，评论、Chat、附件、Do** 覆盖和时间记录单独确认。批量操作限制数量并分批执行；写入超时时先查询 ClickUp 状态，避免重复副作用。