内容
# MCP ClickUp 服务器
用于将 ClickUp 与 OpenCode、Antigravity（谷歌 IDE）或任何 MCP 兼容客户端集成的模型上下文协议服务器。通过自然语言命令创建任务、查询工作区、分配模块和管理项目工作流程。
---
## 目录
- [功能](#功能)
- [安装](#安装)
- [使用](#使用)
- [更新](#更新)
- [配置](#配置)
- [API 密钥](#api-密钥)
- [每个项目的配置](#每个项目的配置)
- [可用工具](#可用工具)
- [开发](#开发)
- [故障排除](#故障排除)
- [许可证](#许可证)
---
## 功能
| 操作 | 示例命令 |
|--------|----------------|
| 浏览工作区 | "显示我的 ClickUp 工作区" |
| 探索列表 | "我的空间有哪些列表？" |
| 查看状态 | "SIGESP 列表有哪些状态？" |
| 查看模块 | "有哪些模块可用？" |
| 查看团队成员 | "这个工作区有哪些成员？" |
| 创建任务 | "在 SIGESP 中创建一个名为 'Review pending items' 的高优先级任务，模块为 TESORERIA" |
| 更新任务 | "将任务 86cad8gv7 标记为已完成，优先级为高" |
| 分配任务 | "将任务 86cad8gv7 分配给 Luis Sanchez" |
| 创建子任务 | "为任务 86cacpvg1 添加子任务" |
| 添加评论 | "为任务添加评论，内容为 '我已经审核过了'" |
| 删除任务 | "删除测试任务" |
| 列出任务 | "显示 SIGESP 中待处理的任务" |
---
## 安装
在任何项目目录中运行以下命令：
```bash
npx mcp-clickup-server setup
```
设置脚本将：
1. 提示输入 ClickUp API 密钥
2. 将密钥保存到全局配置中
3. 检测 IDE（OpenCode、Antigravity）并注册服务器
4. 可选地将当前项目与 ClickUp 列表关联
安装完成后，重启 IDE。ClickUp 工具将立即可用。
---
## 使用
安装完成后，您可以使用自然语言与 ClickUp 进行交互。助手将根据您的请求自动使用工具。
示例：
- "显示我的工作区"
- "这个工作区有哪些成员？"
- "在 SIGESP 中创建一个名为 'Review Q3 budget' 的任务，分配给 Luis"
- "这个项目有哪些待处理的任务？"
- "为任务 86cad8gv7 添加评论，内容为 '我已经审核过了'"
如果项目已配置了 ClickUp 列表，您可以省略列表名称，助手将自动使用已配置的列表。
---
## 更新
要更新到最新版本而不丢失配置：
```bash
npx mcp-clickup-server update
```
这将保留您的 API 密钥和每个项目的设置。如果您通过 git 安装，它将拉取最新代码，安装依赖项并重建。
### 重新配置项目
要更改与当前项目关联的 ClickUp 列表：
```bash
npx mcp-clickup-server reconfigure
```
这将跳过 API 密钥和依赖项步骤，直接进入项目配置向导。
---
## 配置
### 自动配置
`npx mcp-clickup-server setup` 命令会自动检测和配置支持的 IDE。无需手动步骤。
### 手动配置
如果自动检测失败，请手动添加以下配置。
**对于 OpenCode：**
在 `~/.config/opencode/opencode.json` 中：
```json
{
"mcp": {
"clickup": {
"command": ["node", "/path/to/MCP-CLICKUP/dist/index.js"],
"type": "local"
}
}
}
```
**对于 Antigravity（谷歌 IDE）：**
在 `~/.gemini/config/mcp_config.json` 中：
```json
{
"mcpServers": {
"clickup": {
"command": "node",
"args": ["/path/to/MCP-CLICKUP/dist/index.js"]
}
}
}
```
---
## API 密钥
需要 ClickUp 个人 API 令牌。在以下位置生成：
**设置 > 应用 > API 令牌** 或直接在 https://app.clickup.com/settings/apps
令牌以 `pk_` 开头。服务器按以下优先级顺序解析 API 密钥：
1. `CLICKUP_API_KEY` 环境变量
2. `~/.config/mcp-clickup-server/.env` 中的全局配置文件
3. 项目目录中的本地 `.env` 文件
---
## 每个项目的配置
每个项目都可以与特定的 ClickUp 列表关联，允许助手在创建任务时知道使用哪个列表而无需每次都被告知。
### 设置
在项目目录中运行：
```bash
npx mcp-clickup-server setup
```
在设置过程中，您将被提示配置当前项目。您可以：
1. **粘贴 ClickUp 列表 URL** - 设置会解析 URL 并提取列表和工作区 ID。
2. **交互式浏览工作区** - 从工作区、空间和列表中选择。
3. **手动输入列表 ID** - 如果您已经知道 ID。
4. **跳过** - 稍后配置。
要稍后更改配置，请运行：
```bash
npx mcp-clickup-server reconfigure
```
### 手动配置
在项目根目录中创建 `.mcp-clickup.json` 文件：
```json
{
"project": "我的项目",
"listId": "901513520682",
"listName": "SIGESP",
"workspaceId": "90151439364",
"workspaceName": "Ing. Aron Rojas."
}
```
### 工作原理
当您要求助手创建任务或列出任务而不指定列表时，服务器会检查当前项目目录中是否存在 `.mcp-clickup.json`。如果存在，它将自动使用已配置的列表。
---
## 可用工具
服务器为 ClickUp 交互提供了 16 种工具：
| 工具 | 描述 |
|------|-------------|
| `get_workspaces` | 列出所有可访问的工作区 |
| `get_workspace_members` | 列出成员及其 ID、名称和角色 |
| `get_authenticated_user` | 获取当前用户信息（ID、名称、电子邮件） |
| `get_spaces` | 列出工作区内的空间 |
| `get_folders` | 列出空间内的文件夹 |
| `get_lists` | 列出空间或文件夹内的列表 |
| `get_list_statuses` | 查看列表的可用状态 |
| `get_custom_fields` | 查看自定义字段（例如，模块下拉菜单） |
| `get_tasks` | 列出任务，可选过滤器（包括分配者） |
| `get_task` | 获取任务详细信息（包括分配者） |
| `get_task_comments` | 查看任务评论 |
| `get_project_config` | 获取项目的关联 ClickUp 列表 |
| `create_task` | 创建具有所有字段的完整任务 |
| `update_task` | 更新现有任务 |
| `add_comment` | 为任务添加评论 |
| `delete_task` | 删除任务 |
### create_task 参数
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `listId` | 字符串 | 否* | ClickUp 列表 ID（默认为项目配置） |
| `name` | 字符串 | 是 | 任务标题 |
| `description` | 字符串 | 否 | 支持 Markdown 的描述 |
| `status` | 字符串 | 否 | 初始状态（例如，“待处理”，“进行中”） |
| `priority` | 数字 | 否 | 1（紧急）、2（高）、3（正常）、4（低） |
| `dueDate` | 字符串 | 否 | ISO 日期字符串或毫秒时间戳 |
| `startDate` | 字符串 | 否 | 开始日期（ISO 或时间戳） |
| `tags` | 字符串[] | 否 | 任务标签 |
| `assignees` | 数字[] | 否 | 分配的用户 ID（使用 `get_workspace_members` 查找 ID） |
| `parent` | 字符串 | 否 | 子任务的父任务 ID |
| `customFields` | 数组 | 否 | 自定义字段值（例如，模块分配） |
*如果项目有 `.mcp-clickup.json` 配置，则 `listId` 是可选的。
---
## 开发
```bash
npm run dev # 开发模式，热重载
npm run build # 编译 TypeScript
npm start # 生产模式
npm run update # 从 git 更新（保留配置）
```
---
## 故障排除
**"CLICKUP_API_KEY not found"**
运行 `npx mcp-clickup-server setup` 配置 API 密钥。
**设置后 ClickUp 工具在 IDE 中不显示**
重启 IDE（OpenCode 或 Antigravity）。验证配置文件格式是否正确。
**错误：“值必须是选项索引或 uuid”**
使用 `get_custom_fields` 工具检索下拉字段的可用选项 UUID。在 `customFields` 参数中传递选项 UUID（不是显示名称）。
**服务器无法启动**
确保已安装 Node.js v20 或更高版本。运行 `npm run build` 验证 TypeScript 编译成功。确认 `dist/index.js` 存在。
---
## 许可证
MIT
