clickup-mcp-server: A ClickUp MCP Server

clickup-mcp-server：ClickUp MCP 服务

概述

一个用于与 ClickUp API 交互和自动化的模型上下文协议服务。此服务提供工具，供 AI 系统在 ClickUp 中读取、创建和更新任务、列表与空间。

此 MCP 服务支持 Claude 等 AI 工具与您的 ClickUp 工作区交互，帮助自动化任务管理、项目规划和其他工作流。

功能

此 MCP 服务与 ClickUp 深度集成，提供以下功能：

任务管理

• 创建、更新和删除任务
• 在列表和看板之间移动和复制任务
• 设置任务属性，包括截止日期、优先级和标签
• 创建、查看和管理子任务
• 为任务添加评论和附件
• 支持单个和批量任务操作
• 按状态对任务分组和筛选

工作区组织

• 浏览和管理工作区、空间、文件夹和列表
• 创建、更新和删除空间与文件夹
• 在空间和文件夹中整理列表
• 查看完整的工作区层级结构
• 使用路径表示法高效浏览工作区
• 在空间中或文件夹内创建列表

格式与显示

• 任务描述和评论全面支持 Markdown
• 转换为 HTML，以便在 ClickUp 中正确呈现
• 格式化显示任务详情、列表和层级结构
• 增强复杂项目结构的显示效果

开发者体验

• 完善的错误处理和验证
• 清晰、一致的 API 响应
• 所有工具的详细文档
• 可轻松集成 Claude 和其他 AI 系统

工具

此服务提供以下工具，用于与 ClickUp 交互：

工作区／团队工具

1. get_workspaces

   • 获取所有工作区／团队
   • 输入：无
   • 返回：包含 ID 和名称的工作区列表

2. navigate_workspace

   • 使用路径表示法浏览工作区层级结构
   • 输入：
     • path（string）：工作区层级结构的路径（team_id/space_name/folder_name/list_name）
   • 返回：目标实体的详情及其完整路径

空间工具

3. get_spaces

   • 获取工作区中的所有空间
   • 输入：
     • workspace_id（string）：工作区／团队的 ID
   • 返回：包含 ID 和名称的空间列表

4. create_space

   • 在工作区中创建新空间
   • 输入：
     • workspace_id（string）：工作区／团队的 ID
     • name（string）：新空间的名称
   • 返回：已创建空间的详情

5. get_space_hierarchy

   • 获取空间的完整层级结构，包括文件夹和列表
   • 输入：
     • space_id（string）：空间的 ID
   • 返回：空间的完整层级结构

文件夹工具

6. get_folders

   • 获取空间中的所有文件夹
   • 输入：
     • space_id（string）：空间的 ID
   • 返回：包含 ID 和名称的文件夹列表

7. create_folder

   • 在空间中创建新文件夹
   • 输入：
     • space_id（string）：空间的 ID
     • name（string）：新文件夹的名称
   • 返回：已创建文件夹的详情

8. update_folder

   • 更新文件夹名称
   • 输入：
     • folder_id（string）：要更新的文件夹 ID
     • name（string）：文件夹的新名称
   • 返回：已更新的文件夹详情

9. delete_folder

   • 删除文件夹
   • 输入：
     • folder_id（string）：要删除的文件夹 ID
   • 返回：删除确认

列表/看板工具

10. get_lists

    • 获取空间中的所有列表/看板
    • 输入：
      • space_id（string）：空间的 ID
    • 返回：包含 ID 和名称的列表/看板清单

11. create_list

    • 在空间或文件夹中创建新列表/看板
    • 输入：
      • space_id（string）：空间的 ID
      • name（string）：新列表/看板的名称
      • folder_id（string, optional）：文件夹的 ID（在文件夹中创建列表时使用）
    • 返回：所创建列表/看板的详细信息

12. organize_lists

    • 按位置（空间内或文件夹内）整理列表
    • 输入：
      • space_id（string）：空间的 ID
      • folder_id（string, optional）：特定文件夹的 ID
    • 返回：按所属文件夹整理的列表

任务工具

13. get_tasks

• 获取列表/看板中的所有任务
• 输入：
  • list_id（string）：列表/看板的 ID
• 返回：包含 ID、名称和其他详细信息的任务清单

14. get_tasks_by_status

    • 获取列表/看板中具有特定状态的任务
    • 输入：
      • list_id（string）：列表/看板的 ID
      • status（string）：用于筛选任务的状态
    • 返回：具有指定状态的任务清单

15. create_task

    • 在列表/看板中创建新任务
    • 输入：
      • list_id（string）：列表/看板的 ID
      • name（string）：任务名称
      • description（string, optional）：任务描述
      • priority（number, optional）：任务优先级（1-4）
      • due_date（number, optional）：任务截止日期（毫秒）
      • tags（string[], optional）：要添加到任务的标签名称列表
    • 返回：所创建任务的详细信息

16. get_task

    • 获取特定任务的详细信息
    • 输入：
      • task_id（string）：任务的 ID
    • 返回：任务的完整详细信息，包括描述、状态等

17. update_task

    • 更新任务属性
    • 输入：
      • task_id（string）：任务的 ID
      • name（string, optional）：新任务名称
      • description（string, optional）：新任务描述
      • priority（number, optional）：新任务优先级（1-4）
      • due_date（number, optional）：新的截止日期（毫秒）
      • tags（string[], optional）：新的标签名称列表
    • 返回：更新后的任务详细信息

18. update_task_status

    • 更新任务状态
    • 输入：
      • task_id（string）：任务的 ID
      • status（string）：任务的新状态
    • 返回：更新后的任务详细信息

19. assign_task

    • 为任务分配用户
    • 输入：
      • task_id（string）：任务的 ID
      • assignee_ids（string[]）：要分配给任务的用户 ID 列表
    • 返回：分配确认信息

20. get_task_subtasks

    • 获取任务的子任务
    • 输入：
      • task_id（string）：任务的 ID
    • 返回：包含详细信息的子任务清单

21. delete_task

    • 删除任务
    • 输入：
      • task_id（string）：要删除的任务 ID
    • 返回：删除确认信息

22. move_task

    • 将任务移至其他列表/看板
    • 输入：
      • task_id（string）：要移动的任务 ID
      • list_id（string）：目标列表/看板的 ID
    • 返回：更新后的任务详细信息

23. duplicate_task

    • 复制任务，可选择将其复制到其他列表/看板
    • 输入：
      • task_id（string）：要复制的任务 ID
      • list_id（string, optional）：目标列表/看板的 ID
    • 返回：复制后任务的详细信息

24. create_subtask

    • 为父任务创建子任务
    • 输入：
      • parent_task_id (string)：父任务的 ID
      • name (string)：子任务名称
      • description (string, optional)：子任务描述
      • priority (number, optional)：子任务优先级（1-4）
      • due_date (number, optional)：子任务截止日期，以毫秒为单位
      • tags (string[], optional)：子任务的标签名称列表
    • 返回：已创建子任务的详情

25. add_comment

    • 向任务添加评论
    • 输入：
      • task_id (string)：任务的 ID
      • comment_text (string)：评论内容
    • 返回：已添加评论的详情

26. add_attachment

    • 通过 URL 向任务添加附件
    • 输入：
      • task_id (string)：任务的 ID
      • attachment_url (string)：要添加的附件 URL
    • 返回：已添加附件的详情

27. bulk_update_tasks

    • 一次性更新列表中的多个任务
    • 输入：
      • list_id (string)：包含这些任务的列表/看板 ID
      • task_ids (string[])：要更新的任务 ID 列表
      • name (string, optional)：所有任务的新名称
      • description (string, optional)：所有任务的新描述
      • status (string, optional)：所有任务的新状态
      • priority (number, optional)：所有任务的新优先级（1-4）
      • due_date (number, optional)：所有任务的新截止日期，以毫秒为单位
      • tags (string[], optional)：所有任务的新标签名称列表
    • 返回：批量更新确认信息

28. bulk_delete_tasks

    • 一次性删除多个任务
    • 输入：
      • task_ids (string[])：要删除的任务 ID 列表
    • 返回：批量删除确认信息

自定义字段工具

29. get_custom_fields

    • 获取列表/看板的所有自定义字段
    • 输入：
      • list_id (string)：列表/看板的 ID
    • 返回：自定义字段列表，包含其 ID、名称、类型和配置

30. set_custom_field_value

    • 使用字段 ID 设置任务的自定义字段值
    • 输入：
      • task_id (string)：任务的 ID
      • field_id (string)：自定义字段的 ID
      • value (any)：要设置的自定义字段值
    • 返回：自定义字段更新确认信息

31. set_custom_field_value_by_name

    • 使用字段名称设置任务的自定义字段值
    • 输入：
      • task_id (string)：任务的 ID
      • list_id (string)：列表的 ID（按名称查找自定义字段时需要）
      • field_name (string)：自定义字段的名称
      • value (any)：要设置的自定义字段值
    • 返回：自定义字段更新确认信息

32. remove_custom_field_value

    • 移除任务的自定义字段值
    • 输入：
      • task_id (string)：任务的 ID
      • field_id (string)：自定义字段的 ID
    • 返回：自定义字段移除确认信息

安装

前提条件

• Python 3.10 或更高版本
• 拥有 API 密钥的 ClickUp 账户

使用 uv（推荐）

使用 uv 时，无需进行特定安装。我们将使用 uvx 直接运行 clickup-mcp-server。

uv --directory "/path/to/clickup-mcp-server" run clickup-mcp-server --api-key YOUR_API_KEY

或者使用 .env 文件（参见配置部分）。

使用 PIP

或者，你也可以通过 pip 安装 clickup-mcp-server：

pip install clickup-mcp-server

安装后，可以使用以下命令将其作为脚本运行：

python -m clickup_mcp_server --api-key YOUR_API_KEY

配置

API 密钥

使用此服务需要 ClickUp API 密钥。你可以从 ClickUp API 设置获取。

可以通过以下两种方式提供 API 密钥：

1. 命令行参数：--api-key YOUR_API_KEY
2. .env 文件中的环境变量：

   CLICKUP_API_KEY=your_api_key_here
   

在 Claude Desktop 中使用

将以下内容添加到 claude_desktop_config.json：

"mcpServers": {
  "clickup": {
    "command": "uvx",
    "args": ["clickup-mcp-server", "--api-key", "YOUR_API_KEY"]
  }
}

"mcpServers": {
  "clickup": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "-e", "CLICKUP_API_KEY=YOUR_API_KEY", "mcp/clickup"]
  }
}

"mcpServers": {
  "clickup": {
    "command": "python",
    "args": ["-m", "clickup_mcp_server", "--api-key", "YOUR_API_KEY"]
  }
}

在 VS Code 中使用

如需手动安装，请将以下 JSON 代码块添加到 VS Code 的用户设置（JSON）文件中。按下 Ctrl + Shift + P 并输入 Preferences: Open Settings (JSON) 即可打开该文件。

也可以将其添加到工作区中的 .vscode/mcp.json 文件，以便与他人共享配置。

请注意，.vscode/mcp.json 文件中不需要 mcp 键。

{
  "mcp": {
    "servers": {
      "clickup": {
        "command": "uvx",
        "args": ["clickup-mcp-server"],
        "env": {
          "CLICKUP_API_KEY": "YOUR_API_KEY"
        }
      }
    }
  }
}

Docker 安装方式：

{
  "mcp": {
    "servers": {
      "clickup": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "-e", "CLICKUP_API_KEY=YOUR_API_KEY",
          "mcp/clickup"
        ]
      }
    }
  }
}

在 Zed 中使用

添加到 Zed 的 settings.json 中：

"context_servers": [
  "mcp-server-clickup": {
    "command": {
      "path": "uvx",
      "args": ["clickup-mcp-server"]
    },
    "env": {
      "CLICKUP_API_KEY": "YOUR_API_KEY"
    }
  }
],

"context_servers": {
  "mcp-server-clickup": {
    "command": {
      "path": "python",
      "args": ["-m", "clickup_mcp_server"]
    },
    "env": {
      "CLICKUP_API_KEY": "YOUR_API_KEY"
    }
  }
},

使用场景示例

使用 Claude 管理任务

Claude 可以帮助你管理 ClickUp 任务：

1. 制定任务计划： 请 Claude 根据 ClickUp 中的特定任务制定计划。Claude 将会：

   • 按名称或 ID 查找任务
   • 分析任务描述和子任务
   • 生成用于完成任务的结构化计划

2. 任务自动化： 对于包含代码相关说明的任务，Claude 可以：

   • 从 ClickUp 获取任务详情
   • 将任务状态更新为“In Progress”
   • 根据任务要求实现代码
   • 完成后勾选子任务
   • 完成后将状态更新为“Ready for Review”

3. 任务报告： 请 Claude 生成特定状态任务的摘要：

   • 获取所有标记为“In Progress”的任务
   • 汇总状态报告并估算完成时间
   • 为阻碍项或依赖项创建新任务

4. 自定义字段管理： Claude 可以使用自定义字段来完善工作流：

   • 列出项目中的所有自定义字段，查看可用元数据
   • 创建 PR 时设置“GitHub Pull Request URL”等自定义字段的值
   • 更新“Sprint”“Story Points”或“Priority”等项目跟踪字段
   • 示例：“为此分支创建一个 PR，并将 GitHub URL 添加到相关 ClickUp 任务的‘GitHub Pull Request URL’自定义字段中”

调试

使用 -v 或 -vv 标志运行服务，以提高日志详细程度：

uvx clickup-mcp-server -vv

你可以使用 MCP inspector 调试服务：

npx @modelcontextprotocol/inspector uvx clickup-mcp-server

开发

设置开发环境

1. 克隆仓库：

   git clone https://github.com/yourusername/clickup-mcp-server.git
   cd clickup-mcp-server
   

2. 安装开发依赖项：

   uv pip install -e ".[dev]"
   

3. 运行测试：

   pytest
   

Docker 构建

构建 Docker 镜像：

docker build -t mcp/clickup .

实现状态

此 MCP 服务实现了大部分 ClickUp 核心功能。以下详细列出了已实现的功能以及计划在未来实现的功能。

任务管理 ✅

所有核心任务管理功能均已实现：

工作区组织 ✅

所有工作区组织功能均已实现：

其他功能 🔧

部分高级功能已实现，其他功能计划在未来版本中推出：

图例：

• ✅ 已实现
• 🔄 计划中或进行中

许可证

此 MCP 服务采用 MIT 许可证。您可以自由使用、修改和分发此软件，但须遵守 MIT 许可证的条款和条件。更多详情请参阅项目仓库中的 LICENSE 文件。