ClickUp MCP Server

ClickUp MCP 服务

一个用于集成 ClickUp 的模型上下文协议服务实现，可让 AI 助手与 ClickUp 工作区交互。

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

快速开始

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

1. 生成个人 API 令牌： 在 ClickUp 设置中，前往“My Settings” > “Apps”并生成令牌。
2. 配置 MCP 客户端（例如 Claude for Desktop）： 为客户端配置服务时，设置所需的环境变量。

MCP 客户端配置示例：

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

3. 重启 MCP 客户端。

MCP 客户端会在需要时自动下载并启动此服务。

通过 Smithery 安装

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

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 的 Docs API（尤其是 v2，部分操作现已使用 v3）存在限制。内容主要以 Markdown 格式处理。高级格式或复杂嵌入内容可能无法完全支持。ClickUp 的 V3 /docs 端点目前不支持通过 API 直接删除文档；请通过归档或页面操作来管理 Doc 生命周期。

• clickup_search_docs：搜索工作区（团队）中的 Docs。
  • 必需：workspace_id。
  • 可选：query（字符串）、include_archived（布尔值）。
• clickup_create_doc：创建新 Doc。
  • 必需：workspace_id、name。
  • 可选：parent（包含 id 和 type 的对象）、visibility（字符串："private"、"workspace"、"public"）、create_page（布尔值）。
• clickup_get_doc_pages：获取特定 Doc 中的页面列表。
  • 必需：doc_id。
• clickup_create_doc_page：在特定 Doc 中创建新页面。
  • 必需：workspace_id、doc_id、name（页面标题）。
  • 可选：content（Markdown）、orderindex（数字，但 v3 API 可能不会使用它）、parent_page_id（字符串）、sub_title（字符串）、content_format（字符串）。
• clickup_get_doc_page_content：获取特定 Doc 页面的内容（Markdown）。
  • 必需：workspace_id、doc_id、page_id。
  • 可选：content_format（字符串）。
• clickup_edit_doc_page_content：更新特定 Doc 页面的内容和／或标题。
  • 必需：workspace_id、doc_id、page_id、content（Markdown）。
  • 可选：title（字符串，对应 API 中的 name）、sub_title（字符串）、content_edit_mode（字符串："replace"、"append"、"prepend"）、content_format（字符串）。

视图管理

• clickup_get_views：获取指定父级资源（Team、Space、Folder 或 List）的所有视图。
  • 必填：parent_id（父级资源的 ID）、parent_type（字符串："team"、"space"、"folder" 或 "list"）。
• clickup_create_view：在 Team、Space、Folder 或 List 中创建新视图。
  • 必填：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 开始的分页页码）。

开发

1. 克隆仓库：

   git clone <repository_url>
   cd clickup-mcp-server
   

2. 安装依赖：

   npm install
   

3. 在根目录中创建 .env 文件，并添加你的 CLICKUP_PERSONAL_TOKEN：

   CLICKUP_PERSONAL_TOKEN=your_actual_personal_api_token_here
   LOG_LEVEL=debug
   

4. 以开发模式（Stdio）启动： 服务将在 stdin/stdout 上监听 MCP 消息。

   npm run dev
   

   此命令使用 ts-node-dev 运行 src/index.ts。

5. 构建生产版本：

   npm run build
   

   此命令会将 TypeScript 编译到 dist/。

6. 运行测试：

   npm test
   

   此命令会运行位于 src/__tests__ 中的 Jest 单元测试。请确保你有 .env.test 文件（参见 src/__tests__/setup.ts）。

使用 MCP Inspector 进行测试

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

1. 确保可以使用 CLICKUP_PERSONAL_TOKEN。你可以：
   • 在运行 Inspector 前将其设为 shell 环境变量。
   • 如果 MCP Inspector UI 提供了设置服务环境变量的选项，则在其中设置。
   • 将其写入本地 .env 文件（因为 src/index.ts 会加载 dotenv）。
2. 使用服务运行 Inspector：

   npx @modelcontextprotocol/inspector node --loader ts-node/esm src/index.ts
   

   Inspector UI 应会启动，你可以连接到服务并调用其工具。

安全

• 使用你的 ClickUp Personal API Token 进行身份验证。**请妥善保管此令牌并对其保密。**请将其视同密码。
• 服务要求调用方 MCP 客户端或开发环境通过环境变量提供 CLICKUP_PERSONAL_TOKEN。
• 配置系统包含针对 ENCRYPTION_KEY 的逻辑，且 src/security.ts 中有加密函数，但 ClickUpService 目前不会将其用于 Personal API Token。
• 默认情况下，当 LOG_LEVEL=info 时，不会记录敏感数据（如令牌本身）。调试级别可能会记录更多详情。
• ClickUp API 调用的速率限制通过记录剩余请求数来处理（参见 ClickUpService）。

故障排除

常见问题

1. 身份验证错误（ClickUp API 返回 401）

   • 确认 CLICKUP_PERSONAL_TOKEN 环境变量已正确设置，并且服务器进程可以访问。
   • 确保令牌有效，且未在 ClickUp 设置中撤销。
   • 检查服务器日志中是否有 ClickUpService 关于身份验证的消息。

2. ClickUp API 限流

   • 服务器会记录 ClickUp API 响应中的限流信息。
   • 如果频繁触发限流，说明使用量较高。服务器本身不实现排队或复杂的退避机制，axios 默认行为除外。

3. 服务器无法启动 / 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 文件

测试流水线修复