点击アップ-mcp服务器

Name: 点击アップ-mcp服务器
Author: Nazruden

作者：Nazruden17 星标更新：2025-11-17

安装使用来源：spider==github.com

项目介绍

ClickUp MCP Server

这是一个用于与 ClickUp 集成的 Model Context Protocol 服务器实现，使 AI 助手能够与 ClickUp 工作空间进行交互。

此服务器根据 MCP 规范通过 Stdio 运行，当被 MCP 客户端调用时。

快速开始

此服务器使用您的 ClickUp 个人 API 令牌 进行身份验证。

生成个人 API 令牌：在您的 ClickUp 设置中，导航到“我的设置” > “应用”并生成一个令牌。
配置您的 MCP 客户端（例如，Claude for Desktop）：在配置服务器时设置所需的环境变量。

MCP 客户端配置示例片段：

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["@nazruden/clickup-server"],
      "env": {
        "CLICKUP_PERSONAL_TOKEN": "your_personal_api_token_here"
      }
    }
  }
}

重启您的 MCP 客户端。

当需要时，MCP 客户端会自动下载并启动服务器。

通过 Smithery 安装

要通过 Smithery 自动安装 ClickUp MCP Server for Claude Desktop：

npx -y @smithery/cli install @Nazruden/clickup-mcp-server --client claude

环境变量

必需

CLICKUP_PERSONAL_TOKEN：您的 ClickUp 个人 API 令牌。这是服务器与 ClickUp API 身份验证所必需的。

可选

LOG_LEVEL：服务器的日志级别。支持 error、warn、info、debug。默认为 info。
ENCRYPTION_KEY：持久的 32 字节十六进制编码密钥。配置系统 (src/config/app.config.ts) 加载或生成此密钥，而 src/security.ts 包含加密/解密函数。然而，当前机制未用于加密 ClickUpService 中的个人 API 令牌认证流程中的 CLICKUP_PERSONAL_TOKEN。
PORT：服务器端口。默认的 Stdio MCP 服务器模式不使用此选项，但如果明确添加了 HTTP 传输或额外的 HTTP 功能（如单独的健康检查端点），则可能相关。如果读取，默认配置为 3000。

可用工具

以下 MCP 工具已实现：

任务管理

clickup_create_task：在 ClickUp 列表中创建新任务。
- 需要：list_id，name。
- 可选：description，status，priority，assignees，due_date，time_estimate，tags。
clickup_update_task：更新现有任务的属性。
- 需要：task_id。
- 可选：任何可写的 ClickUpTask 属性。

团队及列表管理

clickup_get_teams：检索所有可访问的团队（ClickUp API v2 中的工作区）。
clickup_get_lists：获取特定文件夹中的所有列表。
- 需要：folder_id。

看板管理

clickup_create_board：在 ClickUp 空间中创建新的看板。
- 需要：space_id，name。

空间管理

clickup_get_spaces：检索给定工作区（团队）的所有空间。
- 需要：team_id（工作区 ID）。
- 可选：archived（布尔值，默认为 false）。
clickup_create_space：在工作区内创建新的空间。
- 需要：team_id（工作区 ID），name。
- 可选：multiple_assignees（布尔值），features（具有特征标志的对象，如 due_dates，time_tracking 等）。
clickup_get_space：检索特定空间的详细信息。
- 需要：space_id。
clickup_update_space：更新现有的空间。
- 需要：space_id。
- 可选：name，color，private，admin_can_manage，archived，features。
clickup_delete_space：删除空间。
- 需要：space_id。

文件夹管理

clickup_get_folders：检索给定空间内的所有文件夹。
- 需要：space_id。
- 可选：archived（布尔值，默认为 false）。
clickup_create_folder：在空间内创建新的文件夹。
- 需要：space_id，name。
clickup_get_folder：检索特定文件夹的详细信息。
- 需要：folder_id。
clickup_update_folder：更新现有的文件夹。
- 需要：folder_id，name。
clickup_delete_folder：删除文件夹。
- 需要：folder_id。

自定义字段管理

clickup_get_custom_fields：检索给定列表的所有可访问自定义字段。
- 需要：list_id。
clickup_set_task_custom_field_value：设置特定任务上的自定义字段值。
- 需要：task_id，field_id，value。
- 可选：value_options（对象，例如 { "time": true } 对于日期字段）。
clickup_remove_task_custom_field_value：从特定任务中移除/清除自定义字段的值。
- 需要：task_id，field_id。

文档管理

注意：ClickUp 的文档 API（尤其是 v2，现在某些操作使用 v3）存在限制。内容主要以 Markdown 处理。高级格式化或复杂嵌入可能不受完全支持。目前，ClickUp 的 V3 /docs 端点不支持直接通过 API 删除文档；文档生命周期应通过归档或页面操作来管理。

clickup_search_docs：在工作区（团队）中搜索文档。
- 需要：workspace_id。
- 可选：query（字符串），include_archived（布尔值）。
clickup_create_doc：创建新的文档。
- 需要：workspace_id，name。
- 可选：parent（具有 id 和 type 的对象），visibility（字符串："private"，"workspace"，"public"），create_page（布尔值）。
clickup_get_doc_pages：检索特定文档中的页面列表。
- 需要：doc_id。
clickup_create_doc_page：在特定文档中创建新的页面。
- 需要：workspace_id，doc_id，name（页面标题）。
- 可选：content（Markdown），orderindex（数字，尽管 v3 API 可能不会使用它），parent_page_id（字符串），sub_title（字符串），content_format（字符串）。
clickup_get_doc_page_content：检索特定文档页面的内容（Markdown）。
- 需要：workspace_id，doc_id，page_id。
- 可选：content_format（字符串）。
clickup_edit_doc_page_content：更新特定文档页面的内容和/或标题。
- 需要：workspace_id，doc_id，page_id，content（Markdown）。
- 可选：title（字符串，映射到 API 的 'name'），sub_title（字符串），content_edit_mode（字符串："replace"，"append"，"prepend"），content_format（字符串）。

视图管理

clickup_get_views：检索给定父资源（团队、空间、文件夹或列表）的所有视图。
- 需要：parent_id（父资源的 ID），parent_type（字符串："team"，"space"，"folder" 或 "list"）。
clickup_create_view：在团队、空间、文件夹或列表中创建新的视图。
- 需要：parent_id，parent_type，name（字符串：新视图的名称），type（字符串：视图类型，例如 "list"，"board"，"calendar"，"gantt"）。
- 可选：grouping，divide，sorting，filters，columns，team_sidebar，settings（定义视图配置的对象）。
clickup_get_view_details：检索特定视图的详细信息。
- 需要：view_id。
clickup_update_view：更新现有的视图。
- 需要：view_id。
- 可选：name（字符串），grouping，divide，sorting，filters，columns，team_sidebar，settings。
clickup_delete_view：删除视图。
- 需要：view_id。
clickup_get_view_tasks：检索属于特定视图的任务。
- 需要：view_id。
- 可选：page（数字：分页的 0 索引页码）。

开发

克隆仓库：

git clone <repository_url>
cd clickup-mcp-server

安装依赖项：
```
npm install
```
在根目录创建一个 .env 文件，并添加您的 CLICKUP_PERSONAL_TOKEN：
```
CLICKUP_PERSONAL_TOKEN=your_actual_personal_api_token_here
LOG_LEVEL=debug
```
开发模式启动（Stdio）：服务器将在 stdin/stdout 上监听 MCP 消息。
```
npm run dev
```
这使用 ts-node-dev 来运行 src/index.ts。
构建生产版本：
```
npm run build
```
这将 TypeScript 编译到 dist/。
运行测试：
```
npm test
```
这将运行位于 src/__tests__ 的 Jest 单元测试。确保您有一个 .env.test 文件（参见 src/__tests__/setup.ts）。

使用 MCP Inspector 测试

您可以使用 MCP Inspector 在本地测试服务器：

确保您的 CLICKUP_PERSONAL_TOKEN 可用。您可以：
- 在运行 inspector 之前，在 shell 环境中设置它。
- 如果 MCP Inspector UI 提供设置服务器环境变量的选项，则在其中设置它。
- 将其放在本地 .env 文件中（因为 src/index.ts 加载 dotenv）。
使用服务器运行 Inspector：
```
npx @modelcontextprotocol/inspector node --loader ts-node/esm src/index.ts
```
Inspector UI 应该启动，允许您连接到服务器并调用其工具。

安全性

使用您的 ClickUp 个人 API 令牌进行身份验证。请确保此令牌安全且保密。 就像密码一样对待它。
服务器期望 CLICKUP_PERSONAL_TOKEN 由消费 MCP 客户端或开发环境通过环境变量提供。
配置系统包括 ENCRYPTION_KEY 的逻辑，src/security.ts 包含加密函数，但这些当前未应用于 ClickUpService 中的个人 API 令牌。
默认情况下，LOG_LEVEL=info 不会记录敏感数据（如令牌本身）。调试级别可能会记录更多细节。
ClickUp API 调用的速率限制通过日志记录剩余请求来处理（参见 ClickUpService）。

故障排除

常见问题

身份验证错误（来自 ClickUp API 的 401 错误）
- 验证您的 CLICKUP_PERSONAL_TOKEN 环境变量是否正确设置并且对服务器进程可用。
- 确保令牌有效且未在您的 ClickUp 设置中撤销。
- 查看服务器日志中的 ClickUpService 关于身份验证的消息。
ClickUp API 的速率限制
- 服务器记录来自 ClickUp API 响应的速率限制信息。
- 如果频繁达到速率限制，这表明使用量很高。服务器本身没有实现排队或复杂的回退，除非 axios 默认执行。
服务器无法启动 / MCP Inspector 连接问题
- 确保 CLICKUP_PERSONAL_TOKEN 已设置。
- 如果使用 npm run dev，检查控制台中的 TypeScript 或 ts-node-dev 错误。
- 如果使用 MCP Inspector 并带有 node --loader ts-node/esm src/index.ts，确保 ts-node 和项目依赖项已正确安装。
- 检查来自 src/index.ts 或 ClickUpService 的控制台错误。

获取服务器日志

当通过 npm run dev 或 npm start 运行时，日志输出到控制台。
如果由 MCP 客户端（如 Claude for Desktop）运行，通常由该客户端管理日志。对于 Claude for Desktop，日志通常可以在以下位置找到：
- Windows：%USERPROFILE%\AppData\Local\Claude\Logs\mcp<server_name_and_id><process_id>.log（路径可能略有不同）
- macOS：~/Library/Logs/Claude/mcp/<server_name_and_id><process_id>.log（路径可能略有不同）

支持

如果您发现这个项目有用，请考虑买我一杯咖啡以支持持续开发和维护。

许可证

MIT 许可证 - 详情见 LICENSE 文件