ClickUp AI助手添加福利群：解决AI开发者的「MCP实战痛点」
github详情内容
ClickUp MCP 服务器
这是一个用于 ClickUp 集成的模型上下文协议（MCP）服务器实现，使 AI 助手能够与 ClickUp 工作区进行交互。
该服务器根据 MCP 规范通过 Stdio 运行，当 MCP 客户端调用时启动。
快速开始
该服务器使用您的 ClickUp 个人 API 令牌 进行身份验证。
- 生成个人 API 令牌： 在您的 ClickUp 设置中，导航到“我的设置” > “应用”并生成一个令牌。
- 配置您的 MCP 客户端（例如 Claude for Desktop）： 在为客户端配置服务器时设置所需的环境变量。
MCP 客户端的配置示例：
{
"mcpServers": {
"clickup": {
"command": "npx",
"args": ["@nazruden/clickup-server"],
"env": {
"CLICKUP_PERSONAL_TOKEN": "您的个人 API 令牌"
}
}
}
}
- 重启您的 MCP 客户端。
服务器将在需要时由 MCP 客户端自动下载并启动。
通过 Smithery 安装
要通过 Smithery自动为 Claude Desktop 安装 ClickUp MCP 服务器：
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 的文档 API（尤其是 v2，部分操作现在使用 v3）存在限制。内容主要作为 Markdown 处理。高级格式或复杂嵌入可能无法完全支持。ClickUp 的 V3 /docs 端点目前不支持通过 API 直接删除文档；通过归档或页面操作管理文档生命周期。
clickup_search_docs：在工作区（团队）内搜索文档。- 需要：
workspace_id。 - 可选：
query（字符串）、include_archived（布尔值）。
- 需要：
clickup_create_doc：创建新文档。- 需要：
workspace_id、name。 - 可选：
parent（带有id和type的对象）、visibility（字符串："private"、"workspace"、"public"）、create_page（布尔值）。
- 需要：
clickup_get_doc_pages：检索特定文档中的页面列表。- 需要：
doc_id。
- 需要：
clickup_create_doc_page：在特定文档中创建新页面。- 需要：
workspace_id、doc_id、name（页面标题）。 - 可选：
content（Markdown）、orderindex（数字，尽管 v3 API 可能不使用它）、parent_page_id（字符串）、sub_title（字符串）、content_format（字符串）。
- 需要：
clickup_get_doc_page_content：检索特定文档页面的内容（Markdown）。- 需要：
workspace_id、doc_id、page_id。 - 可选：
content_format（字符串）。
- 需要：
clickup_edit_doc_page_content：更新特定文档页面的内容和/或标题。- 需要：
workspace_id、doc_id、page_id、content（Markdown）。 - 可选：
title（字符串，映射到 API 的 'name'）、sub_title（字符串）、content_edit_mode（字符串："replace"、"append"、"prepend"）、content_format（字符串）。
- 需要：
视图管理
clickup_get_views：检索给定父资源（团队、空间、文件夹或列表）的所有视图。- 需要：
parent_id（父资源的 ID）、parent_type（字符串："team"、"space"、"folder" 或 "list"）。
- 需要：
clickup_create_view：在团队、空间、文件夹或列表中创建新视图。- 需要：
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 索引页码）。
- 需要：
开发
-
克隆仓库：
git clone <仓库地址> cd clickup-mcp-server -
安装依赖：
npm install -
在根目录下创建
.env文件并添加您的CLICKUP_PERSONAL_TOKEN：CLICKUP_PERSONAL_TOKEN=您的实际个人 API 令牌 LOG_LEVEL=debug -
以开发模式启动（Stdio）： 服务器将在 stdin/stdout 上监听 MCP 消息。
npm run dev这将使用
ts-node-dev运行src/index.ts。 -
为生产环境构建：
npm run build这将 TypeScript 编译到
dist/。 -
运行测试：
npm test这将运行位于
src/__tests__中的 Jest 单元测试。确保您有一个.env.test文件（参见src/__tests__/setup.ts）。
使用 MCP Inspector 进行测试
您可以使用 MCP Inspector 在本地测试服务器：
- 确保您的
CLICKUP_PERSONAL_TOKEN可用。您可以：- 在运行 Inspector 之前在 shell 环境中设置它。
- 如果 MCP Inspector UI 提供服务器环境变量的选项，则在其中设置它。
- 将其放在本地的
.env文件中（因为src/index.ts加载了dotenv）。
- 使用服务器运行 Inspector：
Inspector UI 应启动，允许您连接到服务器并调用其工具。npx @modelcontextprotocol/inspector node --loader ts-node/esm src/index.ts
安全
- 使用您的 ClickUp 个人 API 令牌进行身份验证。请确保此令牌安全保密。 像对待密码一样对待它。
- 服务器期望通过 MCP 客户端或开发环境提供
CLICKUP_PERSONAL_TOKEN环境变量。 - 配置系统包含
ENCRYPTION_KEY的逻辑，src/security.ts中有加密函数，但ClickUpService当前未应用于个人 API 令牌。 - 默认情况下，
LOG_LEVEL=info不会记录敏感数据（如令牌本身）。调试级别可能会记录更多详细信息。 - ClickUp API 调用的速率限制通过记录剩余请求来处理（参见
ClickUpService）。
故障排除
常见问题
-
认证错误（来自ClickUp API的401错误）
- 验证您的
CLICKUP_PERSONAL_TOKEN环境变量是否正确设置，并且服务器进程可以访问。 - 确保令牌有效且未在您的ClickUp设置中被撤销。
- 检查服务器日志中来自
ClickUpService的关于认证的消息。
- 验证您的
-
ClickUp API的速率限制
- 服务器日志中记录了来自ClickUp API响应的速率限制信息。
- 如果频繁达到速率限制，这表明使用量较高。服务器本身除了
axios默认可能执行的排队或复杂退避机制外，并未实现其他机制。
-
服务器无法启动 / 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（路径可能略有不同）
- Windows:
支持
如果您觉得这个项目有帮助，请考虑请我喝杯咖啡，以支持持续的开发和维护。
许可证
MIT许可证 - 详情请参阅LICENSE文件
测试管道修复
腾讯云开发者
Copyright © 2013 - 2026 Tencent Cloud. All Rights Reserved. 腾讯云 版权所有
深圳市腾讯计算机系统有限公司 ICP备案/许可证号：粤B2-20090059 
粤公网安备44030502008569号
腾讯云计算（北京）有限责任公司 京ICP证150476号 | 京ICP备11018762号