Clickup Mcp

面向 AI 助手的 ClickUp MCP

Model Context Protocol（MCP）服务，可让 AI 助手与 ClickUp 工作区交互。通过自然语言获取完整的任务上下文，包括评论和图片；搜索项目；创建和更新任务；通过评论协作；以及跟踪时间。

此 MCP 与官方 ClickUp MCP 的对比

另请参阅：官方 ClickUp MCP 文档

功能	此 MCP	官方 ClickUp MCP
设置	本地 npm/npx 安装	远程 MCP（无需安装）
身份验证	仅 API 密钥	仅 OAuth
任务上下文	完整，包含评论、状态历史记录和内嵌图片	需要多次调用工具才能获取完整上下文
图片支持	读取和写入：支持内嵌图片，并智能控制大小；还会自动上传 	通过单独的工具调用上传；base64 上限约为 200KB
搜索	对近期任务进行模糊搜索（范围有限）	完整的 ClickUp 搜索数据库
文档	CRUD 操作	CRUD 操作 + 文档搜索
时间跟踪	查看和创建条目	计时器和条目
聊天集成	不支持	支持
连接的应用	不支持	Connected Search
最适合	编码工具、自动化、收集上下文	聊天应用、任务管理
支持	社区（开源）	ClickUp 官方支持

在以下情况下选择此 MCP：

• 你需要包含内嵌图片的丰富任务上下文，以供 AI 编码工具使用
• 你想通过本地文件路径将截图写入工单（在本地运行时，它会自行读取文件，而不是使用 base64）
• 你需要通过 API 密钥进行身份验证，以用于自动化或 CI/CD 流水线
• 你想使用针对开发工作流优化的 read-minimal 模式

在以下情况下选择官方 MCP：

• 你需要 OAuth 身份验证，以满足企业安全合规要求
• 你需要聊天集成或 Connected Search 功能
• 你需要官方支持，且不想在本地安装

你可以做什么

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

Agent 编码与开发：

• “查看 CU-abc123，能帮我找到相关代码吗？”
• “能否按照 https://app.clickup.com/t/12a23b45c 中的描述构建仪表盘？”
• “检查任务 CU-xyz789，并修复评论中提到的错误”
• “实现集成任务中描述的 API 端点”

时间追踪与效率提升：

• “为 XYZ 项目的客户会议登记 2 小时”
• “我这周在开发任务上花了多少时间？”
• “为身份验证功能的代码审查登记 30 分钟”

智能搜索与发现：

• “我在哪个任务中提到了 CSV 导入？”
• “查找所有与支付网关集成相关的任务”
• “显示用户报告登录问题的任务”

日常工作流管理：

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

丰富的上下文与协作：

• “显示所有关于用户身份验证任务的评论”
• “数据库迁移的最新进展是什么？”
• “在设计任务中添加一条关于新线框图的评论”

文档管理：

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

主要功能

🔍 智能搜索

• 在任务名称、描述和评论中进行模糊匹配
• 支持多语言搜索，满足国际团队需求
• 按受指派人、项目、状态和元数据筛选

💬 完整上下文

• 评论历史和团队讨论（最多 250 条顶层评论），包括串接的评论回复
• 带有嵌入图片的任务描述
• 列表描述和项目指南
• 支持页面导航的文档内容
• 访问完整的任务历史和决策记录

⏱️ 时间追踪

• 记录带说明的时间条目
• 查看历史时间日志和条目
• 按任务或日期范围查询时间条目

📋 任务与文档管理

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

🔒 安全功能

• 描述仅追加：描述字段绝不会被覆盖；新内容会带时间戳安全追加
• 常规字段更新：可正常更新状态、优先级、受指派人、标签和日期（可通过 ClickUp 历史记录轻松还原）

安装

先决条件

对于所有安装方式，你都需要：

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

选项 1：MCPB Bundle（推荐用于 Claude Desktop）

从我们的发布页面下载预构建的 Bundle。此方法无需安装 Node.js。

你会看到一个配置页面，系统会提示你输入 API 密钥和团队 ID。

选项 2：NPX 安装

此方法会自动更新到最新版本，推荐希望使用最新功能的用户采用。

适用于 Claude Desktop、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 Desktop：Settings > Developer > Edit Config
• 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	❌	❌	✅	为任务添加评论，或通过 parent_comment_id 在评论串中回复
editComment	❌	❌	✅	在 24 小时内修改自己的评论，无需另发后续评论
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 服务可通过环境变量进行配置。在桌面扩展（.mcpb）安装程序中，API 密钥、团队 ID、主要语言、上传大小限制和评论编辑时限可通过表单字段设置；其余变量必须直接在服务环境中设置。

• 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 的最大响应大小（以 MB 为单位）。此设置会通过智能大小预算，在限制范围内保留最重要的图片。默认值为 1。
• MAX_UPLOAD_SIZE_MB：（可选）撰写评论或描述时上传的单张图片的最大大小。默认值为 10。
• CLICKUP_COMMENT_EDIT_WINDOW_HOURS：（可选）创建评论后，editComment 仍可修改该评论的时长。默认值为 24。设为 0 可完全禁用评论编辑。
• 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 的 Agent 负责，但 MCP 会在获得语言提示时提供更具体的建议。

Markdown 格式支持

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

示例

使用 Markdown 创建任务：

Create a task called "API Integration" with description:
# API Integration Requirements

## Authentication
- Implement OAuth 2.0 flow
- Add JWT token validation
- **Priority**: High security standards

## Endpoints
1. `/api/users` - User management
2. `/api/data` - Data retrieval
3. `/api/webhook` - Event notifications

## Testing
- [ ] Unit tests for auth flow
- [ ] Integration tests
- [ ] Load testing with 1000+ concurrent users

> **Note**: This replaces the legacy REST implementation

See related task: https://app.clickup.com/t/abc123

仅追加式更新（安全）： 更新任务描述时，内容会安全地追加：

[Existing task description content]

---
**Edit (2024-01-15):** Added new acceptance criteria based on client feedback:
- Must support mobile responsive design
- Performance requirement: < 2s load time

这样既能确保现有内容不会丢失，也能保留清晰的审计记录。

在工单中写入图片

addComment、editComment、createTask 和 updateTask 支持将图片作为普通 Markdown 内容。由于此服务在本地运行，因此会自行读取文件——只需提供本地路径即可：

Ist umgesetzt. So sieht es aus:

**1. Login öffnen** – der Kunde gibt nur seine E-Mail-Adresse ein.

![Die Login-Maske fragt nur nach der E-Mail](/Users/me/shots/login.png)

接受的来源：本地文件路径、data: URI、http(s) URL（下载后再重新上传），以及现有的 ClickUp 附件 URL（嵌入时不会重新上传）。

注意：

• 优先使用路径，而非 base64。 路径只占用少量令牌；同一张截图以 data: URI 形式传入时，在请求中占用的空间约为文件大小的 4/3。
• 说明文字会成为附件文件名，ClickUp 会在图片下方显示该文件名——因此请撰写易读的说明文字。
• 编号列表中的图片会打乱 ClickUp 的编号。 请像上文一样，将操作步骤写成加粗行，并在步骤之间插入图片。
• 只会上传真正的 PNG/JPEG/GIF/WebP 文件——检查的是文件内容，而非扩展名。若文件未通过检查，写入操作会中止：addComment、editComment 和 updateTask 会报告所有无效引用且不做任何更改，因此可以修正 Markdown 后重试调用，而不会创建重复内容。createTask 会在创建工单前检查图片；若之后上传失败，则只会报告警告，因为此时工单已经存在。
• 附件始终属于某个工单，因此文档页面无法通过这种方式嵌入上传的文件。

性能与限制

针对 AI 工作流进行了优化：

• 智能图片处理：智能分配大小预算，在遵守数量限制（MAX_IMAGES，默认值：4）和响应总大小限制（MAX_RESPONSE_SIZE_MB，默认值：1MB）的同时，优先处理最新的图片
• 搜索范围：在最近的 1000-3000 个工单中搜索，以避免触及速率限制（具体数量因端点而异）
• 搜索结果：最多返回 50 个最相关的匹配项，避免向 Agent 返回过多结果

当前范围：

• 侧重于工单级操作，而非工作区批量管理
• 针对对话式 AI 工作流进行了优化，而非数据迁移
• 旨在提升工作效率，而非执行管理操作

这些限制确保了可靠的性能，同时涵盖开发上下文和工作效率管理中最常见的用例。

许可证

MIT