ClickUp MCP for AI助手

模型上下文协议（MCP）服务器使AI助手能够与ClickUp工作空间进行交互。获取完整的任务上下文，包括评论和图片，跨项目搜索，创建和更新任务，通过评论协作，并跟踪时间——所有这些都可以通过自然语言实现。

您可以做什么

将自然语言转化为强大的ClickUp操作：

代理编码与开发：

• "查看CU-abc123，你能找到相关的代码吗？"
• "你能按照https://app.clickup.com/t/12a23b45c中描述的那样构建仪表板吗？"
• "检查任务CU-xyz789并修复评论中提到的bug"
• "实现集成任务中描述的API端点"

时间跟踪与生产力：

• "为XYZ项目的客户会议预订2小时"
• "这周我在开发任务上花了多少时间？"
• "记录30分钟用于认证功能的代码审查"

智能搜索与发现：

• "我提到了CSV导入的任务是什么？"
• "查找所有与支付网关集成相关联的任务"
• "显示用户报告登录问题的所有任务"

日常流程管理：

• "今天我需要做什么？"
• "创建一个任务来修复前端列表中的仪表板bug"
• "将API文档任务更新为‘审核’状态"
• "哪些任务阻碍了移动应用的发布？"

丰富的上下文与协作：

• "显示用户认证任务上的所有评论"
• "数据库迁移的最新更新是什么？"
• "在设计任务中添加关于新线框图的评论"

文档管理：

• "在hauptsache.net空间中查找有关职位发布的文档"
• "在所有空间中搜索API文档"
• "阅读开发空间中的API文档"
• "为移动应用项目创建一个新的需求文档"
• "用今天的决策更新会议纪要"
• "产品策略空间中有哪些文档？"

主要特性

🔍 智能搜索

• 跨任务名称、描述和评论的模糊匹配
• 支持多语言搜索以满足国际团队的需求
• 根据分配人、项目、状态和元数据过滤

💬 完整上下文

• 完整的评论历史和团队讨论
• 嵌入图片的任务描述
• 列表描述和项目指南
• 文档内容及页面导航
• 访问完整的任务历史和决策

⏱️ 时间跟踪

• 登记带有描述的时间条目
• 查看历史时间日志和条目
• 根据任务或日期范围查询时间条目

📋 任务与文档管理

• 使用Markdown描述创建和更新任务
• 创建、读取和更新文档和页面
• 添加评论并与团队成员协作
• 管理优先级、截止日期、分配人和标签
• 处理时间估计和自定义字段值

🔒 安全特性

• 追加模式描述：描述字段永远不会被覆盖——新的内容会安全地追加并带有时间戳
• 常规字段更新：状态、优先级、分配人、标签和日期可以正常更新（通过ClickUp的历史记录很容易撤销）

安装

先决条件

对于所有安装方法，您需要：

• 您的CLICKUP_API_KEY（个人资料图标 > 设置 > 应用 > API令牌 —— 通常以pk_开头）
• 您的CLICKUP_TEAM_ID（当您在设置中时，URL中的7-10位数字）

方案1：MCPB捆绑包（推荐用于Claude桌面版）

从我们的发布页面下载预构建的捆绑包。此方法不需要Node.js安装。

您将获得一个配置屏幕，在该屏幕上提示您输入您的API密钥和团队ID。

方案2：NPX安装

此方法自动更新到最新版本，适合希望使用最新功能的用户。

对于Claude桌面版、Windsurf、Cursor及其他：

在您的MCP配置文件中添加以下内容：

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": [
        "@hauptsache.net/clickup-mcp@latest"
      ],
      "env": {
        "CLICKUP_API_KEY": "your_api_key",
        "CLICKUP_TEAM_ID": "your_team_id"
      }
    }
  }
}

将your_api_key和your_team_id替换为您实际的ClickUp凭据。

在哪里添加此配置：

• Claude桌面版：设置 > 开发者 > 编辑配置
• Windsurf：添加到您的MCP配置文件
• Cursor：通过MCP设置面板配置

方案3：编码工具集成

Claude Code（CLI）：

claude mcp add --scope user clickup \
  --env CLICKUP_API_KEY=YOUR_KEY \
  --env CLICKUP_TEAM_ID=  YOUR_ID \
  --env CLICKUP_MCP_MODE=read-minimal \
  --env MAX_IMAGES=16 \
  --env MAX_RESPONSE_SIZE_MB=4 \
  -- npx -y @hauptsache.net/clickup-mcp

Claude Code可以处理大量图像，因此建议增加限制。

注意CLICKUP_MCP_MODE=read-minimal。这是我的使用建议，但您可以自由选择其他模式之一。

OpenAI Codex： 在您的~/.codex/config.toml文件中添加以下行：

[mcp_servers.clickup]
command = "npx"
args = ["-y", "@hauptsache.net/clickup-mcp@latest"]
env = { "CLICKUP_API_KEY" = "YOUR_KEY", "CLICKUP_TEAM_ID" = "YOUR_ID", "CLICKUP_MCP_MODE" = "read-minimal" }

Codex似乎无法处理来自MCP的图像。详情见此问题。

注意CLICKUP_MCP_MODE=read-minimal。这是我的使用建议，但您可以自由选择其他模式之一。

MCP模式与可用工具

ClickUp MCP支持三种操作模式，以平衡功能、安全性和性能：

• 🚀 read-minimal：适用于AI编码助手和上下文收集
• 📖 read：完全只读访问，用于项目探索和工作流理解
• ✏️ write（默认）：完整的功能，用于任务管理和生产力工作流

工具	read-minimal	read	write	描述
getTaskById	✅	✅	✅	获取完整的任务细节，包括评论、图片和元数据
addComment	❌	❌	✅	向任务添加评论以促进协作
updateTask	❌	❌	✅	更新任务（状态、优先级、分配人等），具有安全追加模式的描述
createTask	❌	❌	✅	使用完整的Markdown支持创建新任务
searchTasks	✅	✅	✅	通过内容、关键词、分配人或项目上下文查找任务
searchSpaces	❌	✅	✅	浏览工作区结构、项目组织和文档
getListInfo	❌	✅	✅	获取列表详情和可用于任务创建的状态
updateListInfo	❌	❌	✅	对列表描述进行安全追加模式更新（保留现有内容）
getTimeEntries	❌	✅	✅	查看时间条目并分析项目中的时间花费
createTimeEntry	❌	❌	✅	登记时间条目以跟踪任务
readDocument	❌	✅	✅	获取文档详情、页面结构和内容，带有导航
searchDocuments	❌	✅	✅	搜索文档，按名称和空间进行模糊匹配和空间过滤
updateDocumentPage	❌	❌	✅	更新现有页面内容或名称，使用替换/追加模式
createDocumentOrPage	❌	❌	✅	创建新文档，带有首页，或将页面/子页面添加到现有文档

设置模式

在您的MCP配置中添加模式：

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "@hauptsache.net/clickup-mcp@latest"],
      "env": {
        "CLICKUP_API_KEY": "your_api_key",
        "CLICKUP_TEAM_ID": "your_team_id",
        "CLICKUP_MCP_MODE": "read"
      }
    }
  }
}

配置

此MCP服务器可以通过环境变量进行配置：

• CLICKUP_API_KEY：（必需）您的ClickUp API密钥。
• CLICKUP_TEAM_ID：（必需）您的ClickUp团队ID（以前的工作区ID）。
• CLICKUP_MCP_MODE：（可选）控制可用的工具。选项：read-minimal，read，write（默认）。
• MAX_IMAGES：（可选）getTaskById返回的任务中最大图片数量，默认为4。
• MAX_RESPONSE_SIZE_MB：（可选）getTaskById的最大响应大小（兆字节）。使用智能大小预算，以在限制内容纳最重要的图片。默认为1。
• CLICKUP_PRIMARY_LANGUAGE：（可选）提供您的ClickUp任务中使用的主语言提示（例如，“de”表示德语，“en”表示英语）。这有助于searchTask工具在其描述中为多语言搜索提供更具体的指导。
• LANG：（可选）如果未设置CLICKUP_PRIMARY_LANGUAGE，MCP将检查此标准环境变量（例如，“en_US.UTF-8”，“de_DE”）作为回退，以推断主语言。

语言感知搜索指导

searchTask工具的描述将根据检测到的主要语言动态调整：

• 如果CLICKUP_PRIMARY_LANGUAGE或LANG暗示了一种已知的主要语言（例如德语），工具的描述将特别建议提供英文和检测到的语言（例如德语）的搜索词，以获得最佳结果。
• 如果没有检测到主要语言，则会提供针对多语言工作区的一般性建议。

此功能旨在提高搜索效果，当用户查询的语言（通常是英语）与ClickUp任务中的语言不同时，而无需让MCP本身执行翻译。向MCP调用的责任仍然在于提供双语搜索词的代理，但MCP会在有语言提示的情况下提供更具体的建议。

Markdown格式支持

任务描述和列表文档支持完整的Markdown格式：

示例

使用Markdown创建任务：

创建一个名为“API集成”的任务，描述如下：
# API集成需求

## 认证
- 实现OAuth 2.0流程
- 添加JWT令牌验证
- **优先级**：高标准的安全性

## 端点
1. `/api/users` - 用户管理
2. `/api/data` - 数据检索
3. `/api/webhook` - 事件通知

## 测试
- [ ] 认证流程的单元测试
- [ ] 集成测试
- [ ] 使用1000+并发用户的负载测试

> **注意**：这取代了旧的REST实现

参见相关任务：https://app.clickup.com/t/abc123

安全追加更新： 在更新任务描述时，内容会被安全追加：

[现有任务描述内容]

---
**编辑（2024-01-15）**：基于客户反馈新增验收标准：
- 必须支持移动响应式设计
- 性能要求：<2秒加载时间

这确保不会丢失任何现有内容，同时保持清晰的审计轨迹。

性能与限制

优化用于AI工作流：

• 智能图像处理：智能大小预算优先考虑最近的图片，同时尊重数量（MAX_IMAGES，默认：4）和总响应大小限制（MAX_RESPONSE_SIZE_MB，默认：1MB）
• 搜索范围：在最近的1000-3000个任务中搜索，以防止触及速率限制（确切数量因端点而异）
• 搜索结果：返回最多50个最相关的匹配项，以防止向代理发送过多的结果

当前范围：

• 专注于任务级别的操作，而不是批量工作区管理
• 优化用于对话式AI工作流，而非数据迁移
• 设计用于提升生产力，而非行政操作

这些限制确保可靠性能的同时，涵盖了开发上下文和生产力管理中最常见的使用场景。

许可

MIT