ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Klavis ClickUp MCP Server:让 AI Agent 通过 MCP 协议管理 ClickUp 任务与项目工作流

Klavis ClickUp MCP Server:让 AI Agent 通过 MCP 协议管理 ClickUp 任务与项目工作流 Klavis ClickUp MCP Server让 AI Agent 通过 MCP 协议管理 ClickUp 任务与项目工作流【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本文以 Klavis 开源仓库中的 ClickUp MCP Servermcp_servers/clickup/为主线完整覆盖官方 README 中介绍的两种部署方式Klavis 托管服务与 Docker 自托管、OAuth 认证机制、21 个可用 MCP 工具及其参数约定并结合仓库源码深入解析双传输SSE StreamableHTTP服务架构、基于ContextVar的逐请求鉴权注入以及把 ClickUp 原始 API 响应归一化为 Klavis 统一 Schema 的实现细节帮助读者既能快速接入该服务也能理解其内部工作原理。一、ClickUp MCP Server 是什么ClickUp MCP Server 是一个基于 Model Context ProtocolMCP的服务器让 AI Agent 通过 ClickUp REST API v2 管理任务、项目与团队协作。按 mcp_servers/clickup/README.md 的定位它提供五大类能力任务管理Task Management创建、读取、更新、完成任务项目操作Project Operations管理 Space、Folder、List 三级结构时间追踪Time Tracking处理工时与生产力指标相关的字段团队协作Team Collaboration管理团队成员与权限自定义字段Custom Fields操作任务的自定义字段与属性。整个实现位于 mcp_servers/clickup/ 目录server.py是服务入口tools/包按对象类型teams、spaces、folders、lists、tasks、comments、users组织所有工具实现Dockerfile与requirements.txt定义容器化构建方式。二、部署方式README 给出两条部署路径Klavis 托管服务免部署、生产推荐和 Docker 自托管可完全控制鉴权数据。2.1 方式一Klavis 托管服务推荐用于生产托管模式无需搭建任何基础设施只需安装 SDK 并创建一个 Server 实例pip install klavis # 或 npm install klavisfrom klavis import Klavis klavis Klavis(api_keyyour-free-key) server klavis.mcp_server.create_server_instance(CLICKUP, user123)其中api_key来自 Klavis 平台的免费 API Keyuser123是userId用于标识在 Klavis 中访问哪个用户的已连接账户与数据——它应是代表你自己、团队或组织的唯一标识。ClickUp 属于需要 OAuth 的集成托管服务会接管整个 OAuth 流程SDK 返回的实例中带有 OAuth 授权 URL将其交给用户在浏览器中完成授权后该 Server 实例即可供任意 MCP 客户端使用。2.2 方式二Docker 自托管自托管镜像为ghcr.io/klavis-ai/clickup-mcp-server:latestREADME 提供两种运行形态# 拉取最新镜像 docker pull ghcr.io/klavis-ai/clickup-mcp-server:latest # 形态 A带 OAuth 支持需 Klavis API Key docker run -p 5000:5000 -e KLAVIS_API_KEY$KLAVIS_API_KEY \ ghcr.io/klavis-ai/clickup-mcp-server:latest # 形态 B不带 OAuth直接使用 ClickUp API Token docker run -p 5000:5000 -e AUTH_DATA{access_token:your_clickup_api_token_here} \ ghcr.io/klavis-ai/clickup-mcp-server:latest两种形态的差异在源码中可以直接印证。server.py 的extract_access_token()定义了鉴权信息的解析优先级环境变量AUTH_DATA若已设置则优先解析其中的 JSON 并取出access_token字段——对应上面形态 B的静态 Token 方案请求头x-auth-data若未设置AUTH_DATA则从每个请求的x-auth-data头中读取Base64 编码的 JSON解析出access_token。该头部同时兼容 SSE 请求对象与 StreamableHTTP 的 scope 字典两种入参形态支持按请求动态携带不同用户的凭据这也是形态 A通过 Klavis 托管 OAuth 后能够逐请求注入 Token 的机制基础。解析失败时仅记录WARNING日志并返回空字符串不会抛异常中断连接。端口与启动参数服务默认监听 5000 端口可通过环境变量CLICKUP_MCP_SERVER_PORT覆盖见 server.py。server.py由click提供命令行入口支持三个参数参数默认值说明--port5000或CLICKUP_MCP_SERVER_PORT环境变量HTTP 监听端口--log-levelINFO日志级别DEBUG / INFO / WARNING / ERROR / CRITICAL--json-responsefalse启用后 StreamableHTTP 以 JSON 响应代替 SSE 流依赖requirements.txt 锁定了核心运行时——mcp1.11.0MCP 官方 SDK、pydantic、fastapi、uvicorn[standard]、python-dotenv、requests、httpx、click、starlette。Dockerfile 基于python:3.12-slim先安装系统依赖gcc再按先 COPY requirements 装包、后 COPY 源码的顺序构建以利用 Docker 缓存最终EXPOSE 5000并以python server.py启动。三、服务架构双传输端点与鉴权上下文阅读 server.py 可以看出该服务并不是单一的传输实现而是用 Starlette 同时挂载了两套 MCP 传输Starlette 路由 ├── /sse (GET) SSE 传输端点 ├── /messages/ (Mount) SSE 消息回传端点 └── /mcp (Mount) StreamableHTTP 端点无状态模式SSE 传输SseServerTransport(/messages/)适合传统 MCP 客户端StreamableHTTP 传输StreamableHTTPSessionManager以statelessTrue无状态方式运行json_response参数决定是否以 SSE 流返回便于更现代的客户端接入。鉴权注入的关键在两个 handler 中handle_sse 与 handle_streamable_http每次请求进入时先调用extract_access_token()取出 Token再写入tools/base.py中定义的ContextVar# mcp_servers/clickup/tools/base.py CLICKUP_API_BASE_URL https://api.clickup.com/api/v2 auth_token_context: ContextVar[str] ContextVar(auth_token)工具函数在发起 API 调用时通过get_auth_token()从上下文读取 Token并用try/finally确保请求结束后auth_token_context.reset(token)复位。这种设计保证了同一进程并发处理多个 MCP 会话时每个请求携带各自的 ClickUp 凭据、互不串扰——这正是多用户 OAuth 场景下按请求携带x-auth-data能成立的原因。所有出站请求统一走 make_clickup_request()以https://api.clickup.com/api/v2为 Base URL将 Token 直接放入Authorization头支持 GET/POST/PUT/DELETE 四种方法并用response.raise_for_status()把 HTTP 错误转为异常。四、21 个可用工具全览list_tools()在 server.py 中完整注册了 21 个工具全部以clickup_为前缀并带有category与readOnlyHint注解只读工具标注readOnlyHint: True。下表汇总工具、参数与对应的 ClickUp API v2 端点端点列依据tools/各模块源码中make_clickup_request()的调用整理4.1 团队与工作区Team / Workspace工具参数底层 APIclickup_get_teams无只读GET /teamclickup_get_workspaces无只读get_teams的别名GET /team4.2 Space 管理工具参数底层 APIclickup_get_spacesteam_id必填GET /team/{team_id}/spaceclickup_create_spaceteam_id、name必填color、private默认falsePOST /team/{team_id}/spaceclickup_update_spacespace_id必填name、color、privatePUT /space/{space_id}4.3 Folder 管理工具参数底层 APIclickup_get_foldersspace_id必填只读GET /space/{space_id}/folderclickup_create_folderspace_id、name必填POST /space/{space_id}/folderclickup_update_folderfolder_id、name必填PUT /folder/{folder_id}4.4 List 管理工具参数底层 APIclickup_get_listsfolder_id与space_id二选一必填其一只读GET /folder/{id}/list或GET /space/{id}/listclickup_create_listname必填folder_id/space_id二选一可选content、due_dateISO 日期串、priority1urgent、2high、3normal、4low、assignee、statusPOST /folder/{id}/list或POST /space/{id}/listclickup_update_listlist_id必填name、content、due_date、priority、assignee、unset_status默认falsePUT /list/{list_id}4.5 Task 管理核心工具参数底层 APIclickup_get_taskslist_id必填archived默认false、include_closed默认false、page默认0、subtasks默认false只读GET /list/{list_id}/taskclickup_get_task_by_idtask_id必填include_subtasks默认false只读GET /task/{task_id}clickup_create_tasklist_id、name必填description、assignees用户 ID 数组、status、priority、due_dateUnix 毫秒时间戳POST /list/{list_id}/taskclickup_update_tasktask_id必填name、description、status、priority、due_datePUT /task/{task_id}clickup_search_tasksteam_id、query必填start默认0、limit默认20只读GET /team/{team_id}/task带query参数从源码结构看clickup_get_tasks暴露的工具参数是其 Python 实现 get_tasks() 的一个子集底层实现还支持order_by、reverse、statuses[]、assignees[]、tags[]、due_date_gt/lt、date_created_gt/lt、date_updated_gt/lt等更细的过滤参数但当前 MCP 工具层只透传了archived、include_closed、page、subtasks四项其余参数使用默认值。若需要在 Agent 侧启用更强的过滤可直接参考该实现进行扩展。4.6 Comment 协作工具参数底层 APIclickup_get_commentstask_id必填只读GET /task/{task_id}/commentclickup_create_commenttask_id、comment_text必填notify_all默认true通知所有任务关注者POST /task/{task_id}/commentclickup_update_commentcomment_id、comment_text必填PUT /comment/{comment_id}4.7 用户与成员工具参数底层 APIclickup_get_user无只读返回当前 Token 对应的用户GET /userclickup_get_team_membersteam_id必填只读GET /team/{team_id}/member4.7 工具调用的错误处理call_tool()server.py对每个工具先做必填参数校验如缺少team_id直接返回Error: team_id parameter is required文本未知工具名返回Unknown tool: {name}所有异常被统一捕获后以Error: {异常信息}的TextContent返回给客户端同时用logger.exception()记录完整堆栈。工具结果统一以json.dumps(result, indent2)格式化为带缩进的 JSON 文本返回。五、响应归一化从 ClickUp 原始 JSON 到 Klavis 统一 SchemaKlavis 的一个核心设计是把各家 SaaS 的原始响应转换为平台统一的 Schema以便上层 Agent 以一致的结构消费数据。ClickUp 的实现全部集中在 tools/normalize.py通用normalize()函数接收目标字段名 → 源路径点号分隔字符串或 Lambda 转换函数的映射表用安全的点号路径访问get_path()从原始 JSON 中取值值为None的字段直接排除产出精简、干净的字典分层映射规则USER_RULES、MEMBER_RULES、TEAM_RULES、SPACE_RULES、FOLDER_RULES、STATUS_RULES、LIST_RULES、ASSIGNEE_RULES、TAG_RULES、PRIORITY_RULES、TASK_RULES、COMMENT_RULES每层规则可递归引用例如TASK_RULES中的assignees、subtasks会逐条再套用各自规则归一化命名风格转换ClickUp 返回的snake_case字段date_created、profilePicture混排被统一映射为camelCasecreatedAt、avatarUrl并做字段语义对齐如status.status→status取状态名而非嵌套对象、private→isPrivate、task_count→taskCount兜底逻辑例如COMMENT_RULES的text字段依次尝试comment_text、text_content、字符串型comment三个来源容忍 API 不同版本/端点的返回差异。以clickup_get_tasks为例get_tasks()调用 ClickUp 后执行normalize_tasks(result)最终返回形如{tasks: [ {id, customId, name, description, status, dueDate, listId, assignees: [...], subtasks: [...]}, ... ]}的结构Agent 无需感知 ClickUp 原始 JSON 的嵌套细节。六、MCP 客户端接入配置服务启动后标准 MCP 客户端只需指向对应端点即可例如 StreamableHTTP 端点{ mcpServers: { clickup: { url: http://localhost:5000/mcp/ } } }SSE 客户端则指向http://localhost:5000/sse。服务启动日志会明确打印两个端点地址见 server.py 的Server starting on port {port} with dual transports日志便于验证。七、小结与延伸阅读该 Server 以约 900 行的server.py加按对象类型拆分的tools/包实现了 ClickUp 项目管理全链路Team → Space → Folder → List → Task → Comment的 MCP 工具化并通过ContextVar请求级鉴权与统一响应归一化支撑多租户 OAuth 场景README 中标注的 Time Tracking / Custom Fields 能力在工具参数层面体现为time_estimate、timeSpent归一化字段、check_required_custom_fields等字段见 tasks.py 的底层实现签名当前工具层暴露的参数是其子集从源码结构看存在明确的扩展空间项目贡献指南见 CONTRIBUTING.md许可协议为 Apache 2.0见 LICENSE。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表