使用说明

clickup mcp服务器：clickup mcp服务器

概述

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

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

特性

此MCP服务器提供与ClickUp的全面集成，提供以下功能：

任务管理

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

工作区组织

导航和管理工作区、空间、文件夹和列表
创建、更新和删除空间和文件夹
在空间和文件夹中组织列表
查看全面的工作空间层次结构
使用路径符号在工作空间中高效导航
在空间或文件夹中创建列表

格式化和显示

完全支持任务描述和注释的标记
在ClickUp中正确呈现的HTML转换
任务详细信息、列表和层次结构的格式化显示
增强复杂项目结构的显示

开发者体验

全面的错误处理和验证
清晰一致的API响应
所有工具的详细文档
易于与Claude和其他AI系统集成

工具

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

工作区/团队工具

get_workspaces
- 获取所有工作区/团队
- 输入：无
- 返回：包含ID和名称的工作区列表
navigate_workspace
- 使用路径表示法在工作区层次结构中导航
- 输入：
  - path （string）：工作区层次结构的路径（team_id/space_name/folder_name/list_name）
- 返回：目标实体及其完整路径的详细信息

空间工具

get_spaces
- 获取工作区中的所有空格
- 输入：
  - workspace_id （string）：工作区/团队的ID
- 返回：包含ID和名称的空格列表
create_space
- 在工作空间中创建新空间
- 输入：
  - workspace_id （string）：工作区/团队的ID
  - name （string）：新空间的名称
- 返回：创建空间的详细信息
get_space_hierarchy
- 获取空间的完整层次结构，包括文件夹和列表
- 输入：
  - space_id （string）：空间的ID
- 返回：空间的完整层次结构

文件夹工具

get_folders
- 获取空间中的所有文件夹
- 输入：
  - space_id （string）：空间的ID
- 返回：包含ID和名称的文件夹列表
create_folder
- 在空间中创建新文件夹
- 输入：
  - space_id （string）：空间的ID
  - name （string）：新文件夹的名称
- 返回：创建文件夹的详细信息
update_folder
- 更新文件夹的名称
- 输入：
  - folder_id （string）：要更新的文件夹的ID
  - name （string）：文件夹的新名称
- 返回：已更新文件夹详细信息
delete_folder
- 删除文件夹
- 输入：
  - folder_id （string）：要删除的文件夹的ID
- 返回：确认删除

列表/板工具

get_lists
- 获取空间中的所有列表/板
- 输入：
  - space_id （string）：空间的ID
- 返回：带有ID和名称的列表/板列表
create_list
- 在空间或文件夹中创建新列表/板
- 输入：
  - space_id （string）：空间的ID
  - name （string）：新列表/板的名称
  - folder_id （字符串，可选）：文件夹的ID（如果在文件夹中创建列表）
- 返回：创建的列表/板的详细信息
organize_lists
- 按位置（在空间或文件夹中）组织列表
- 输入：
  - space_id （string）：空间的ID
  - folder_id （字符串，可选）：特定文件夹的ID
- 返回：按包含文件夹组织的列表

任务工具

get_tasks

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

get_tasks_by_status
- 获取列表/板中具有特定状态的任务
- 输入：
  - list_id （string）：列表/板的ID
  - status （string）：按状态筛选任务
- 返回：具有指定状态的任务列表
create_task
- 在列表/板中创建新任务
- 输入：
  - list_id （string）：列表/板的ID
  - name （string）：任务名称
  - description （字符串，可选）：任务描述
  - priority （数字，可选）：任务优先级（1-4）
  - due_date （数字，可选）：任务到期日期（毫秒）
  - tags （string[]，可选）：要添加到任务中的标记名称列表
- 返回：创建的任务的详细信息
get_task
- 获取特定任务的详细信息
- 输入：
  - task_id （string）：任务的ID
- 返回：任务的全部详细信息，包括描述、状态等。
update_task
- 更新任务的属性
- 输入：
  - task_id （string）：任务的ID
  - name （字符串，可选）：新任务名称
  - description （字符串，可选）：新任务描述
  - priority （数字，可选）：新任务优先级（1-4）
  - due_date （数字，可选）：新的截止日期（毫秒）
  - tags （string[]，可选）：新的标记名列表
- 返回：更新任务详细信息
update_task_status
- 更新任务的状态
- 输入：
  - task_id （string）：任务的ID
  - status （string）：任务的新状态
- 返回：更新任务详细信息
assign_task
- 为用户分配任务
- 输入：
  - task_id （string）：任务的ID
  - assignee_ids （string[]）：要分配给任务的用户ID列表
- 退货：确认分配
get_task_subtasks
- 获取任务的子任务
- 输入：
  - task_id （string）：任务的ID
- 返回：子任务列表及其详细信息
delete_task
- 删除任务
- 输入：
  - task_id （string）：要删除的任务的ID
- 返回：确认删除
move_task
- 将任务移动到其他列表/板
- 输入：
  - task_id （string）：要移动的任务的ID
  - list_id （string）：目的地列表/板的ID
- 返回：更新任务详细信息
duplicate_task
- 复制任务，可选地复制到其他列表/板
- 输入：
  - task_id （string）：要复制的任务的ID
  - list_id （字符串，可选）：目标列表/板的ID
- 返回：重复任务的详细信息
create_subtask
- 为父任务创建子任务
- 输入：
  - parent_task_id （string）：父任务的ID
  - name （string）：子任务的名称
  - description （字符串，可选）：子任务描述
  - priority （数字，可选）：子任务优先级（1-4）
  - due_date （数字，可选）：子任务到期日期（毫秒）
  - tags （string[]，可选）：子任务的标记名称列表
- 返回：创建的子任务的详细信息
add_comment
- 向任务添加注释
- 输入：
  - task_id （string）：任务的ID
  - comment_text （string）：评论的文本内容
- 返回：添加评论的详细信息
add_attachment
- 按URL向任务添加附件
- 输入：
  - task_id （string）：任务的ID
  - attachment_url （string）：要添加的附件的URL
- 返回：添加附件的详细信息
bulk_update_tasks
- 一次更新列表中的多个任务
- 输入：
  - list_id （string）：包含任务的列表/板的ID
  - task_ids （string[]）：要更新的任务ID列表
  - name （字符串，可选）：所有任务的新任务名称
  - description （字符串，可选）：所有任务的新任务描述
  - status （字符串，可选）：所有任务的新状态
  - priority （数字，可选）：所有任务的新优先级（1-4）
  - due_date （数字，可选）：所有任务的新截止日期（毫秒）
  - tags （string[]，可选）：所有任务的新标记名称列表
- 返回：批量更新确认
bulk_delete_tasks
- 一次删除多个任务
- 输入：
  - task_ids （string[]）：要删除的任务ID列表
- 返回：确认批量删除

自定义字段工具

get_custom_fields
- 获取列表/板的所有自定义字段
- 输入：
  - list_id （string）：列表/板的ID
- 返回：自定义字段及其ID、名称、类型和配置的列表
set_custom_field_value
- 使用字段ID为任务设置自定义字段值
- 输入：
  - task_id （string）：任务的ID
  - field_id （string）：自定义字段的ID
  - value （任意）：为自定义字段设置的值
- 返回：确认自定义字段更新
set_custom_field_value_by_name
- 使用字段名为任务设置自定义字段值
- 输入：
  - task_id （string）：任务的ID
  - list_id （string）：列表的ID（需要按名称查找自定义字段）
  - field_name （string）：自定义字段的名称
  - value （任意）：为自定义字段设置的值
- 返回：确认自定义字段更新
remove_custom_field_value
- 从任务中删除自定义字段值
- 输入：
  - task_id （string）：任务的ID
  - field_id （string）：自定义字段的ID
- 返回：确认删除自定义字段

安装

先决条件

Python 3.10或更高版本
带有API密钥的ClickUp帐户

使用紫外线（推荐）

使用时 uv 不需要特定的安装。我们将使用 uvx 直接运行 点击mcp服务器.

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

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

使用PIP

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

pip install clickup-mcp-server

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

python -m clickup_mcp_server --api-key YOUR_API_KEY

配置

API密钥

您需要一个ClickUp API密钥才能使用此服务器。你可以从点击API设置.

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

命令行参数： --api-key YOUR_API_KEY
a中的环境变量 .env 文件：
```
CLICKUP_API_KEY=your_api_key_here
```

使用Claude Desktop

将此添加到您的 claude_desktop_config.json:

Using uvx

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

Using docker

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

Using pip installation

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

使用VS代码

对于手动安装，请将以下JSON块添加到VS Code中的用户设置（JSON）文件中。您可以按 Ctrl + Shift + P 和打字 Preferences: Open Settings (JSON).

您可以选择将其添加到名为的文件中 .vscode/mcp.json 在您的工作空间中。这将允许您与他人共享配置。

请注意 mcp 中不需要密钥 .vscode/mcp.json 文件。

{
  "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 settings.json：

Using uvx

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

Using pip installation

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

示例使用场景

Claude的任务管理

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

创建任务计划: 让Claude根据ClickUp中的特定任务创建一个计划。克劳德将：
- 按名称或ID查找任务
- 分析其描述和子任务
- 生成完成任务的结构化计划
任务自动化: 对于包含代码相关指令的任务，Claude可以：
- 从ClickUp获取任务详细信息
- 将任务状态更新为“进行中”
- 根据任务要求实现代码
- 在子任务完成时将其签出
- 完成后将状态更新为“准备审核”
任务报告: 让Claude生成具有特定状态的任务摘要：
- 获取标记为“进行中”的所有任务
- 编制一份状态报告，其中包含完工估算
- 为拦截器或依赖项创建新任务
自定义字段管理: Claude可以使用自定义字段来增强您的工作流程：
- 列出项目中的所有自定义字段以查看可用元数据
- 在创建PR时设置自定义字段值，如“GitHub Pull Request URL”
- 更新项目跟踪字段，如“Sprint”、“故事点”或“优先级”
- 示例：“为此分支创建PR，并将GitHub URL添加到相关ClickUp任务中的'GitHub Pull Request URL'自定义字段中”

调试

使用运行服务器 -v 或 -vv 增加冗长程度的标志：

uvx clickup-mcp-server -vv

您可以使用MCP检查器调试服务器：

npx @modelcontextprotocol/inspector uvx clickup-mcp-server

发展

设置开发环境

克隆存储库：

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

安装开发依赖项：
```
uv pip install -e ".[dev]"
```
运行测试：
```
pytest
```

Docker构建

构建Docker镜像：

docker build -t mcp/clickup .

实施状态

此MCP服务器实现了ClickUp的大部分基本功能。下面是已实现功能和计划在未来实现的功能的详细细分。

任务管理✅

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

功能	状态	描述
创建任务	✅	在任何列表或板中创建新任务
更新任务	✅	修改任务属性，包括名称、描述等
删除任务	✅	从ClickUp中删除任务
移动任务	✅	在不同列表和板之间重新定位任务
重复任务	✅	创建任务的副本，可以选择在不同的位置
设置日期	✅	设置任务的开始日期和截止日期
查看子任务	✅	检索任何父任务的子任务
创建子任务	✅	将子任务添加到现有任务中
管理子任务	✅	更新和删除子任务
添加评论	✅	使用markdown支持向任务添加注释
添加附件	✅	通过URL将文件附加到任务
单次操作	✅	对单个任务执行操作
批量操作	✅	同时对多个任务执行操作

工作区组织✅

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

功能	状态	描述
导航空间	✅	浏览和选择工作区中的空间
导航文件夹	✅	浏览并选择空间中的文件夹
浏览列表	✅	浏览和选择空间或文件夹中的列表
创建空间	✅	在工作空间中创建新空间
创建列表	✅	在空间或文件夹中创建新列表
创建文件夹	✅	在空间内创建新文件夹
组织列表	✅	按位置对列表进行分组和组织
文件夹中的列表	✅	在文件夹中创建和管理列表
查看层次结构	✅	查看完整的工作空间结构
路径导航	✅	使用路径符号高效导航

其他功能🔧

一些高级功能已经实现，其他功能计划在未来的版本中实现：

功能	状态	描述
全局查找	🔄	跨工作区按名称或ID查找项目（计划中）
不区分大小写🔄	匹配名称，不考虑大小写（计划中）
基本降价	✅	支持描述中的基本标记
增强的降价功能	✅	ClickUp中具有适当渲染的高级标记
速率限制	🔄	API速率限制的内置处理（计划中）
错误处理	✅	全面的错误检测和报告
输入验证	✅	API提交前所有输入的验证
API覆盖范围	🔄	支持附加的ClickUp API功能（进行中）

传说：

✅ 实现
🔄 计划中或进行中

许可证

此MCP服务器根据MIT许可证获得许可。这意味着您可以根据MIT许可证的条款和条件自由使用、修改和分发软件。有关更多详细信息，请参阅项目存储库中的LICENSE文件。 EOF</dev/null