# 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 实现，具有严格的类型检查