使用说明
点击MCP服务器
ClickUp集成的模型上下文协议服务器实现，使AI助手能够与ClickUp工作区进行交互。
此服务器通过运行 标准输入输出 当MCP客户端调用时，按照MCP规范。
快速开始
此服务器使用您的 ClickUp 个人 API 令牌 用于身份验证。
- 生成个人API令牌： 在ClickUp设置中，导航到“我的设置”>“应用程序”并生成令牌。
- 配置您的MCP客户端（例如，Claude for Desktop）： 在为客户端配置服务器时设置所需的环境变量。
MCP客户端的示例配置代码段：
{
"mcpServers": {
"clickup": {
"command": "npx",
"args": ["@nazruden/clickup-server"],
"env": {
"CLICKUP_PERSONAL_TOKEN": "your_personal_api_token_here"
}
}
}
}
- 重新启动MCP客户端。
服务器将在需要时由MCP客户端自动下载和启动。
通过Smithery安装
通过以下方式自动安装ClickUp MCP Server for Claude Desktop 史密瑟里:
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包含加密/解密功能。然而，这种机制是 当前未使用 用于加密CLICKUP_PERSONAL_TOKEN在...之内ClickUpService的个人API令牌身份验证流。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“名称”），sub_title（字符串），content_edit_mode（字符串：“replace”、“append”、“prepend”），content_format（字符串）。
- 要求：
视图管理
clickup_get_views：检索给定父资源（团队、空间、文件夹或列表）的所有视图。- 要求：
parent_id（父资源的ID），parent_type（字符串：“团队”、“空间”、“文件夹”或“列表”）。
- 要求：
clickup_create_view：在团队、空间、文件夹或列表中创建新视图。- 要求：
parent_id,parent_type,name（string：新视图的名称），type（字符串：视图的类型，例如“列表”、“板”、“日历”、“甘特图”）。 - 可选：
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 <repository_url> cd clickup-mcp-server -
安装依赖项：
npm install -
创建一个
.env在根目录中创建文件并添加您的CLICKUP_PERSONAL_TOKEN:CLICKUP_PERSONAL_TOKEN=your_actual_personal_api_token_here LOG_LEVEL=debug -
以开发模式（Stdio）启动： 服务器将在stdin/stdout上监听MCP消息。
npm run dev这使用
ts-node-dev运行src/index.ts. -
生产建设：
npm run build这将TypeScript编译为
dist/. -
运行测试：
npm test这将运行位于以下位置的Jest单元测试
src/__tests__.确保你有.env.test文件（参见src/__tests__/setup.ts).
MCP检验员测试
您可以使用MCP检查器在本地测试服务器：
- 确保您的
CLICKUP_PERSONAL_TOKEN可用。您可以：- 在运行检查器之前，在shell环境中设置它。
- 如果它提供了服务器环境变量的选项，请在MCP检查器UI中设置它。
- 在当地买
.env文件（如src/index.ts负载dotenv).
- 使用服务器运行检查器：Inspector UI应该启动，允许您连接到服务器并调用其工具。
npx @modelcontextprotocol/inspector node --loader ts-node/esm src/index.ts
安全
- 使用您的ClickUp个人API令牌进行身份验证。 请确保此令牌的安全性和机密性。 把它当作密码。
- 服务器期望
CLICKUP_PERSONAL_TOKEN由消费MCP客户端或开发环境通过环境变量提供。 - 配置系统包括用于
ENCRYPTION_KEY和src/security.ts具有加密功能，但这是 当前未应用 通过ClickUpService. - 默认情况下，不会记录敏感数据（如令牌本身）
LOG_LEVEL=info调试级别可能会记录更多详细信息。 - ClickUp API调用的速率限制是通过记录剩余请求来处理的（请参阅
ClickUpService).
故障排除
常见问题
-
身份验证错误（401来自ClickUp API）
- 验证您的
CLICKUP_PERSONAL_TOKEN环境变量设置正确，服务器进程可以访问。 - 确保令牌在ClickUp设置中有效且未被撤销。
- 检查服务器日志中来自的消息
ClickUpService关于认证。
- 验证您的
-
API点击率限制
- 服务器记录来自ClickUp API响应的速率限制信息。
- 如果频繁达到速率限制，则表示使用率很高。服务器本身不实现排队或复杂的回退
axios默认情况下可能会这样做。
-
服务器未启动/MCP检查器连接问题
- 确保
CLICKUP_PERSONAL_TOKEN已设置。 - 如果使用
npm run dev，检查TypeScript或ts-node-dev控制台中的错误。 - 如果使用MCP检查器
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，日志通常可以在以下网址找到：
- 窗户：
%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（路径可能略有不同）
- 窗户：
支持
如果你觉得这个项目很有帮助，可以考虑给我买杯咖啡来支持正在进行的开发和维护。
许可证
MIT许可证-有关详细信息，请参阅许可证文件
