ClickUp MCP Server

# 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 参考](#api-参考) - [故障排除](#故障排除) - [许可证](#许可证) --- ## 安装 ### 系统要求 - **Node.js**：18.0.0 或更高版本 - **TypeScript**：5.6.0 或更高版本 - **ClickUp API 令牌**：个人 API 令牌（以 `pk_` 开头） ### 安装依赖 ```bash npm install ``` ### 构建项目 ```bash npm run build ``` --- ## 配置 ### 环境变量 创建 `.env` 文件或设置以下环境变量： | 变量 | 必需 | 描述 | 示例 | |------|------|------|------| | `CLICKUP_TOKEN` | **是** | ClickUp 个人 API 令牌（格式：`pk_xxxxx`） | `pk_12345678_ABCDEFGHIJKLMNOPQRSTUVWXYZ` | | `CLICKUP_TEAM_ID` | 推荐 | 团队/工作空间 ID（自定义任务 ID 必需） | `123456789` | ### 获取 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` ```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 配置： ```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" } } } } ``` --- ## 使用 ### 启动服务器 #### 生产模式 ```bash npm run build npm start ``` #### 开发模式 ```bash 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 - 创建者和指派人 - 标签和优先级 - 截止日期 - 预估时间和已用时间 - 自定义字段 - 依赖项数量 - 列表、文件夹和空间信息 **示例：** ```typescript { "task_id": "ST2IN1-123" } ``` --- ### 2. `analyze_workflow`（分析工作流） 分析任务的工作流，提供见解和建议。 **参数：** - `task_id`（字符串，必需）：ClickUp 任务 ID **返回：** - **进度分析**：当前状态和预估进度百分比 - **时间分析**： - 创建后天数和最后更新天数 - 预估时间与已用时间 - 剩余小时数 - **团队分析**：创建者、指派人、关注者 - **依赖项分析**：被阻塞、阻塞中、依赖于 - **风险因素**：逾期、过时、未分配、超预算 - **建议**：可操作的改进建议 **示例：** ```typescript { "task_id": "8675309" } ``` --- ### 3. `update_status`（更新状态） 更新任务的状态。 **参数：** - `task_id`（字符串，必需）：ClickUp 任务 ID - `status`（字符串，必需）：新状态值（例如，"进行中"、"完成"、"已阻塞"） **验证：** - 状态必须是字母数字字符，包含下划线和空格 - 最多 100 个字符 **示例：** ```typescript { "task_id": "ST2IN1-123", "status": "in progress" } ``` --- ### 4. `update_github_branch`（更新 GitHub 分支） 更新任务的 GitHub 分支自定义字段。 **参数：** - `task_id`（字符串，必需）：ClickUp 任务 ID - `branch_name`（字符串，必需）：GitHub 分支名称 **验证：** - 分支名称只能包含字母数字字符、斜杠、连字符和下划线 - 最多 255 个字符 **示例：** ```typescript { "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 个字符 **示例：** ```typescript { "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 ``` ### 可用脚本 | 脚本 | 描述 | |------|------| | `npm run build` | 编译 TypeScript 到 JavaScript | | `npm start` | 启动服务器（生产模式） | | `npm run dev` | 启动服务器并热重载（开发模式） | | `npm run type-check` | 运行 TypeScript 类型检查，不生成文件 | | `npm run lint` | 运行 TypeScript 编译器检查 | | `npm run clean` | 删除编译文件 | ### 代码风格和约定 - **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 类型 **示例：** ```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 ) { // 实现逻辑 } ``` ```typescript // 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 令牌。 ```bash # 检查令牌格式（应以 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。查看详细日志： ```bash # 在开发模式下查看日志 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 实现，具有严格的类型检查