ClickUp MCP 服务器

由 eBrook Group 开发
版权所有 © 2026 eBrook Group (https://www.ebrook.com.tw)

概述

ClickUp MCP 服务器是一个模型上下文协议（MCP）服务器，提供与 ClickUp 任务管理 API 的无缝集成。它使 AI 助手和自动化工具能够通过标准化接口与 ClickUp 任务交互、分析工作流并管理项目数据。

核心功能

• 任务管理：检索详细的任务信息、更新状态和添加评论

• 工作流分析：分析任务进度、依赖关系、时间跟踪和风险因素

• 自定义字段：更新自定义字段，如 GitHub 分支名称

• 速率限制：内置速率限制以遵守 ClickUp API 约束（100 次请求/分钟）

• 类型安全：完整的 TypeScript 实现，具有严格的类型检查

• 错误处理：全面的错误处理和日志记录

• 自定义任务 ID：支持数字和自定义任务 ID（例如 ST2IN1-123）

目录

• 安装

• 配置

• 使用

• 可用工具

• 开发

• API 参考

• 故障排除

• 许可证

安装

系统要求

• Node.js：18.0.0 或更高版本

• TypeScript：5.6.0 或更高版本

• ClickUp API 令牌：个人 API 令牌（以 pk_ 开头）

安装依赖

npm install

构建项目

npm run build

配置

环境变量

创建 .env 文件或设置以下环境变量：

获取 ClickUp API 令牌

1. 登录 ClickUp

2. 进入设置 → 应用

3. 在 API 令牌下点击生成

4. 复制令牌（以 pk_ 开头）

获取团队 ID

1. 进入你的 ClickUp 工作空间

2. 点击设置 → 工作空间

3. 你的团队 ID 在工作空间设置 URL 或 API 响应中可见

MCP 客户端配置

Claude Desktop 配置

添加到 Claude Desktop 配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/path/to/clickup-mcp/dist/index.js"],
      "env": {
        "CLICKUP_TOKEN": "pk_your_token_here",
        "CLICKUP_TEAM_ID": "your_team_id_here"
      }
    }
  }
}

Cursor 配置

添加到 Cursor MCP 配置：

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/path/to/clickup-mcp/dist/index.js"],
      "env": {
        "CLICKUP_TOKEN": "pk_your_token_here",
        "CLICKUP_TEAM_ID": "your_team_id_here"
      }
    }
  }
}

使用

启动服务器

生产模式

npm run build
npm start

开发模式

npm run dev

基本示例

配置好 MCP 客户端后，你可以使用自然语言与 ClickUp 交互：

• "获取任务 ST2IN1-123 的详细信息"

• "分析任务 8675309 的工作流"

• "将任务 ST2IN1-456 的状态更新为'进行中'"

• "将任务 123 的 GitHub 分支设置为 'feature/new-feature'"

• "向任务 ST2IN1-789 添加评论'审核完成'"

可用工具

1. get_task_details（获取任务详情）

获取 ClickUp 任务的全面信息。

参数：

• task_id（字符串，必需）：ClickUp 任务 ID（数字或自定义格式，如 ST2IN1-123）

返回：

• 任务 ID、名称、状态

• 描述和 URL

• 创建者和指派人

• 标签和优先级

• 截止日期

• 预估时间和已用时间

• 自定义字段

• 依赖项数量

• 列表、文件夹和空间信息

示例：

{
  "task_id": "ST2IN1-123"
}

2. analyze_workflow（分析工作流）

分析任务的工作流，提供见解和建议。

参数：

• task_id（字符串，必需）：ClickUp 任务 ID

返回：

• 进度分析：当前状态和预估进度百分比

• 时间分析：

  • 创建后天数和最后更新天数

  • 预估时间与已用时间

  • 剩余小时数

• 团队分析：创建者、指派人、关注者

• 依赖项分析：被阻塞、阻塞中、依赖于

• 风险因素：逾期、过时、未分配、超预算

• 建议：可操作的改进建议

示例：

{
  "task_id": "8675309"
}

3. update_status（更新状态）

更新任务的状态。

参数：

• task_id（字符串，必需）：ClickUp 任务 ID

• status（字符串，必需）：新状态值（例如，"进行中"、"完成"、"已阻塞"）

验证：

• 状态必须是字母数字字符，包含下划线和空格

• 最多 100 个字符

示例：

{
  "task_id": "ST2IN1-123",
  "status": "in progress"
}

4. update_github_branch（更新 GitHub 分支）

更新任务的 GitHub 分支自定义字段。

参数：

• task_id（字符串，必需）：ClickUp 任务 ID

• branch_name（字符串，必需）：GitHub 分支名称

验证：

• 分支名称只能包含字母数字字符、斜杠、连字符和下划线

• 最多 255 个字符

示例：

{
  "task_id": "ST2IN1-123",
  "branch_name": "feature/add-login-page"
}

**注意：**此工具需要在 ClickUp 工作空间中存在名为"GitHub Branch"的自定义字段。

5. add_comment（添加评论）

向 ClickUp 任务添加评论。

参数：

• task_id（字符串，必需）：ClickUp 任务 ID

• comment_text（字符串，必需）：评论内容

验证：

• 评论文本不能为空

• 最多 10,000 个字符

示例：

{
  "task_id": "ST2IN1-123",
  "comment_text": "已审核并批准。准备部署。"
}

开发

项目结构

clickup-mcp/
├── src/
│   ├── config/
│   │   └── env.ts              # 环境配置
│   ├── services/
│   │   └── clickup.ts          # ClickUp API 服务
│   ├── tools/
│   │   ├── get-task-details.ts # 获取任务详情工具
│   │   ├── analyze-workflow.ts # 工作流分析工具
│   │   ├── update-status.ts    # 更新状态工具
│   │   ├── update-github-branch.ts # 更新分支字段工具
│   │   └── add-comment.ts      # 添加评论工具
│   ├── types/
│   │   └── index.ts            # TypeScript 类型定义
│   ├── utils/
│   │   ├── logger.ts           # 日志工具
│   │   ├── rate-limiter.ts     # 速率限制
│   │   ├── error-sanitizer.ts  # 错误清理
│   │   └── slugify.ts          # 字符串工具
│   ├── server.ts               # MCP 服务器设置
│   └── index.ts                # 入口点
├── dist/                       # 编译后的 JavaScript（自动生成）
├── package.json
├── tsconfig.json
└── README.md

可用脚本

代码风格和约定

• TypeScript：启用严格模式，进行全面的类型检查

• 模块系统：ES 模块（NodeNext）

• 编译目标：ES2022

• 格式化：遵循 TypeScript 最佳实践

• 错误处理：所有错误都被捕获并正确清理

• 日志记录：使用提供的日志工具（debug、info、error）

添加新工具

1. 在 src/tools/ 中创建新文件（例如 my-tool.ts）

2. 实现工具处理函数

3. 在 src/server.ts 中使用 server.tool() 注册工具

4. 使用 Zod 定义参数模式

5. 如需要，在 src/types/index.ts 中更新 TypeScript 类型

示例：

// src/tools/my-tool.ts
import type { ClickUpService } from "../services/clickup.js";
import type { AppConfig } from "../config/env.js";

export async function handleMyTool(
  taskId: string,
  config: AppConfig,
  clickUpService: ClickUpService
) {
  // 实现逻辑
}

// src/server.ts
import { handleMyTool } from "./tools/my-tool.js";

server.tool(
  "my_tool",
  "我的工具描述",
  {
    task_id: z.string().min(1).max(100).describe("任务 ID"),
  },
  async (args) => {
    return await handleMyTool(args.task_id, config, clickUpService);
  }
);

API 参考

ClickUpService 类

与 ClickUp API 交互的主要服务类。

方法

getTask(taskId: string): Promise<ClickUpApiResponse>

通过 ID 获取任务。

updateStatus(taskId: string, status: string): Promise<ClickUpApiResponse>

更新任务的状态。

updateCustomField(taskId: string, fieldId: string, value: string): Promise<ClickUpApiResponse>

更新自定义字段值。

addComment(taskId: string, commentText: string): Promise<ClickUpApiResponse>

向任务添加评论。

findCustomFieldId(taskBody: unknown, fieldName: string): string | null

通过名称查找自定义字段 ID。

formatTaskDetails(task: ClickUpTaskResponse): TaskDetailsSummary

将任务数据格式化为可读摘要。

analyzeTaskWorkflow(task: ClickUpTaskResponse): TaskWorkflowAnalysis

分析任务工作流并提供见解。

速率限制

该服务实现速率限制以遵守 ClickUp 的 API 约束：

• 限制：每分钟 100 次请求

• 实现：令牌桶算法

• 错误代码：超出限制时返回 RATE_LIMIT_001

故障排除

常见问题

1. "CLICKUP_TOKEN 未配置"

解决方案：确保在环境配置中正确设置了 ClickUp API 令牌。

# 检查令牌格式（应以 pk_ 开头）
echo $CLICKUP_TOKEN

2. "自定义任务 ID 需要团队 ID"

解决方案：使用自定义任务 ID（例如 ST2IN1-123）时，设置 CLICKUP_TEAM_ID 环境变量。

3. 找不到任务（404 错误）

可能原因：

• 任务 ID 不正确

• 任务已归档或删除

• 自定义任务 ID 缺少团队 ID

• 权限不足

解决方案：

• 验证任务 ID 是否正确

• 检查 API 令牌是否有权访问该任务

• 确保为自定义 ID 设置了 CLICKUP_TEAM_ID

4. 超出速率限制（429 错误）

解决方案：服务器实现了自动速率限制。稍等片刻再试。限制每分钟重置一次。

5. 找不到"GitHub Branch"字段

解决方案：在 ClickUp 工作空间中创建名为"GitHub Branch"的自定义字段：

1. 进入列表/文件夹/空间设置

2. 点击自定义字段 → 添加字段

3. 创建一个名为"GitHub Branch"的文本字段

调试日志

调试消息记录到 stderr。查看详细日志：

# 在开发模式下查看日志
npm run dev 2>&1 | tee debug.log

# 过滤特定的调试消息
npm run dev 2>&1 | grep "\[DEBUG\]"

技术细节

依赖项

• @modelcontextprotocol/sdk：MCP 协议实现

• zod：模式验证和类型安全

• TypeScript：类型安全开发

• Node.js Fetch API：HTTP 请求（内置）

TypeScript 配置

• 目标：ES2022

• 模块：NodeNext（ES 模块）

• 严格模式：启用所有严格检查

• 源映射：启用调试

• 声明文件：为库使用生成

安全考虑

• API 令牌永远不会记录或在错误消息中暴露

• 所有用户输入都使用 Zod 模式验证

• 错误消息经过清理以防止信息泄漏

• 速率限制防止 API 滥用

贡献

开发工作流

1. Fork 仓库

2. 创建功能分支（git checkout -b feature/my-feature）

3. 进行更改

4. 运行类型检查：npm run type-check

5. 构建项目：npm run build

6. 测试更改

7. 使用描述性消息提交

8. 推送到你的 fork

9. 打开 Pull Request

提交信息格式

遵循格式：ST2IN1-[票号] 简短描述

示例：ST2IN1-12345 添加任务模板支持

许可证

MIT License

版权所有 © 2026 eBrook Group (https://www.ebrook.com.tw)

支持

如有问题、疑问或功能请求，请联系：

eBrook Group
网站：https://www.ebrook.com.tw

更新日志

版本 3.1.0

• 首次公开发布

• 5 个核心工具：get_task_details、analyze_workflow、update_status、update_github_branch、add_comment

• 速率限制实现

• 自定义任务 ID 支持

• 全面的错误处理和日志记录

• 完整的 TypeScript 实现，具有严格的类型检查