ClickUp Serviteur MCP

ClickUp Serviteur MCP

面向 MCP 客户端的可自托管 ClickUp 集成 · TypeScript · Cloudflare Workers · 双 OAuth · MIT 许可证

候选发布版：v0.3.0-beta.1 — 公开源代码测试版（2026 年 11 月 7 日）

官方 MCP 注册表：查看当前的 v0.3.0-beta.1 条目（JSON） · 自托管和注册表设置 · Glama 维护者元数据

ClickUp Serviteur 是一款远程 Model Context Protocol 服务，可向兼容 MCP 的 AI 客户端（包括支持远程 MCP 的 ChatGPT 和 Claude 客户端）提供 ClickUp REST 操作。每个安装实例均由各自的管理员运营，使用独立的 Cloudflare Worker，并验证 MCP 客户端身份及个人的 ClickUp OAuth 凭据。这是一个独立的社区项目，并非 ClickUp 的产品，也与 ClickUp 无关联。

**公开源代码不代表任何人都能访问正在运行的 Worker。**参考企业部署是仅限授权用户访问的安装实例。不要让陌生人连接到该端点，不要复制其他运营者的 Workspace ID，也不要重复使用任何共享凭据。

**注册表条目是用于发现服务的元数据，不代表可公开访问。**每位用户都必须提供自己配置的 Worker 的 HTTPS 主机名；本项目不提供共享的公共 ClickUp 服务。

功能

• 基于真实 ClickUp REST API 的工具，可在限定范围内搜索、创建、分配和编辑任务；还支持列表、文件夹、标签、依赖项、任务链接、评论、自定义字段、时间条目、文档和聊天（以上游 REST API 支持为准）。
• 任务描述支持原生 Markdown 写入和 Markdown 读取；文档和聊天分别处理 text/md 和 text/plain。原生结构化富文本任务评论支持强调、链接、列表／清单／折叠格式、代码、表情符号，以及经过验证的真实 @提及。
• 有限度读取支持的基于文本的 PDF 附件。图片／文件上传适配器和若干较少使用的 API 路径仍有待验收；请参阅已知限制。
• 经过身份验证的企业所有者可清理指定任务及其本人的评论、标签、链接和依赖项，并须明确确认且通过范围验证。此功能并非不受限制的批量删除。
• 通过 OAuth 限定 Workspace 或列表范围；使用个人用户令牌；对存储的凭据进行静态加密；处理 API 速率限制；严格验证请求；在写入结果不确定时不盲目重试。
• 通过 Cloudflare Workers 托管 HTTPS，使用 GitHub Actions 进行 CI、CodeQL 检查和手动触发的受保护部署。

实际完成验证的内容

2026 年 11 月，我们根据确切的 GitHub 构建 SHA 检查了一次受保护的企业部署。使用单独授权的 ClickUp 连接后，我们验证了临时任务的成功创建和分配、原生 Markdown 描述存储、含有已存储格式片段的富文本评论，以及对任务和评论的精确读取。**仅凭 API 读取结果无法证明所有仅限编辑器的内容块都能准确呈现。**并非所有端点或第三方 MCP 客户端都已完成线上验收。

格式兼容性矩阵 · 发行说明 · 项目限制 · 安全

要求

• Node.js 22.20.0 或更高版本以及 npm，用于开发或构建 GitHub Actions。
• Cloudflare 账户，具备 Workers、专用 OAuth KV 命名空间以及所需的 SQLite Durable Objects。
• 用于验证 MCP 用户身份的 GitHub OAuth 凭据；用于授权每个人访问其本人 ClickUp 账户的 ClickUp OAuth 应用凭据。
• 指定的 ClickUp Workspace／列表及单独授权的用户。请配置自己的 ID 和 OAuth 客户端；示例值并非生产授权凭据。
• 能连接受 OAuth 保护的远程服务的 MCP 客户端。

运行检查

git clone https://github.com/cryogenized-spec/ClickUp-Serviteur-MCP.git
cd ClickUp-Serviteur-MCP
npm ci --ignore-scripts --no-audit --no-fund
python3 scripts/check_repo_policy.py
python3 -m unittest discover -s scripts/tests -p 'test_*.py' -v
npm run format:check
npm run lint
npm run typecheck
npm test
npm run build
node scripts/staging-local-smoke.mjs
npm audit --audit-level=high

根包有意设置为 private: true：此测试版在 GitHub 上开源，并非已发布的 npm 包。测试套件全部通过，并不代表云端密钥已配置或 ClickUp 授权已完成。

部署你自己的实例

受维护的部署路径为暂存环境和隔离的公司环境。这些路径只能从经过审查的 main 手动触发；它们不会发布未经身份验证的 ClickUp 网关。

1. Fork 源代码，或创建一个由你控制的仓库。配置两个独立的 OAuth 客户端（用于 MCP 连接的 GitHub 客户端，以及用于上游个人账户的 ClickUp 客户端），并注册准确的 HTTPS 重定向来源。为暂存环境和公司环境使用不同的凭据和存储。
2. 创建 Cloudflare OAuth KV，以及 Worker/Durable Object 绑定。GITHUB_CLIENT_SECRET、CLICKUP_CLIENT_SECRET、CLICKUP_STATE_KEY 和 CLICKUP_TOKEN_KEY 只能存储为 Cloudflare 密钥或适当受保护的部署密钥，切勿存储在由 Git 跟踪的文件中。请在 OAuth 设置中确认密钥编码要求。
3. 配置仓库的 staging 环境变量 STAGING_OAUTH_KV_ID，并设置一个明确的逗号分隔允许列表 STAGING_WORKSPACE_GITHUB_IDS，其中仅包含你授权的 GitHub 身份。公开测试版不再默认使用原始仓库所有者的 GitHub ID。
4. 选择你自己的 Worker 主机名，并配置其 OAuth 回调、公开来源、ClickUp Workspace/List 绑定以及员工映射。请参阅部署和权限和Workspace 目标配置。参考公司环境生成器会验证 COMPANY_OAUTH_KV_ID、COMPANY_WORKSPACE_ID、COMPANY_LIST_ID、COMPANY_GITHUB_OWNER_ID、COMPANY_CLICKUP_USER_ID 和 COMPANY_PUBLIC_ORIGIN。该生成器面向专用的仅限所有者访问的 Worker；如果你需要完全独立的租户模型，请进行相应调整。
5. 触发匹配的 GitHub Actions 手动部署，将 MCP 客户端连接到你自己的 Worker HTTPS 端点，完成两项 OAuth 授权，然后调用 service_info 和 get_clickup_connection_status，以验证已部署的构建和 Workspace 独占访问权限。
6. 先测试读取，再对已批准的临时任务进行写入/读回验证。创建记录前先规划清理步骤。切勿仅凭任务标题进行授权判断。

迁移警告： 此版本重命名了旧版暂存 Worker 和通用 wrangler.jsonc 项目名称。现有暂存环境 URL、OAuth 回调、已存储的 Worker 状态和自定义客户端连接器不会自动迁移。切换端点前，请重新配置新的来源和 Cloudflare 资源，并单独停用旧基础设施。受保护的公司 Worker 名称保持不变。

已知限制

• ClickUp 的公开任务评论 API 未记录原生表格单元格或原生水平分隔线区块；纯文本管道符表格和 --- 可能会按原样显示。请使用任务描述中真正的 Markdown 表格，或改用标签/值评论。
• Docs Markdown 可能无法完整保留仅供编辑器使用的表格、切换项、颜色和其他原生组件。聊天消息和 Docs 的清理覆盖并不完整。
• 没有通用的回滚引擎。删除操作具有破坏性；所有权、Workspace 范围和明确同意仍然很重要。某些上游功能取决于 ClickUp 方案设置和 API 可用性。
• 许多较早的 docs/ 记录属于历史工程证据，而非当前说明。README 和公开发布指南优先于存档笔记中过时的操作说明。
• 源代码可公开读取；连接的私有 Worker、客户数据、员工账户和 API 密钥不会公开。

项目与社区

Bug 报告和功能提案：GitHub Issues。贡献方式：CONTRIBUTING.md。请按照 SECURITY.md 中的说明，私下报告安全问题。版本变更请参阅 CHANGELOG.md。

许可证： MIT。ClickUp 是其各自所有者的商标；本项目不声称获得 ClickUp 的认可。