awesome-coolify

awesome-coolify-mcp

通过编码 Agent 操作 Coolify。
验证连接、发现基础设施、创建工作负载、部署、跟踪日志、诊断故障，并执行设有门控的紧急操作——适用于一个或多个可自托管实例或 Cloud 实例——
直接从 Cursor、Claude、VS Code、Windsurf 或任何支持 MCP 的 Agent 操作。

🇩🇪 Deutsch · Coolify · Model Context Protocol · 安装配置器 ↗

概览 · 为何选择 · 功能 · 架构 · 快速开始 · 安装 · Cloud · 工具 · 提示词 · 安全性 · 路线图

  

_{一键安装使用的是占位凭据——完整操作指南请参阅 安装，也可以使用浏览器配置器安全地填写真实值。}

---

📋 目录

• 概览
• 为什么选择 awesome-coolify-mcp
• 功能
• 工作原理
• 快速开始
• 安装
  • 1. 一键深层链接
  • 2. 安装配置器
  • 3. 手动配置 MCP
• Coolify Cloud
• 支持的客户端
• 环境变量
• MCP 提示词
• 工具参考
• 安全模型
• 结构化错误与重试
• Agent 工作流示例
• 当前状态
• 即将推出
• 本地开发
• 链接

---

🔭 概览

可自托管的 Coolify 是 Heroku/Vercel 风格 PaaS 平台的优秀开源替代方案之一——但过去要将它接入 AI 编码 Agent，往往需要拼凑多个小型且功能重叠的社区 MCP 集成，每个集成都有自己的架构、错误格式，以及对“安全”的不同理解。

awesome-coolify-mcp 1.1.4 用一个由社区维护的 MCP 服务取代了这套拼凑方案，通过简洁的、基于操作的工具接口调用 Coolify 的 REST API 4.1.x。源代码、文档和 npm 发行包都集中在同一个公开仓库 clezcoding/awesome-coolify 中——可安装的软件包仍名为 awesome-coolify-mcp。无需记住数十个近似的工具名称，Agent 只需调用 19 个工具之一，并传入 action 字段：

application({ action: "deploy", uuid: "<app-uuid>", wait: false })
deployment({ action: "watch", deployment_uuid: "<deployment_uuid>", timeout: 300 })
diagnose({ action: "scan" })
emergency({ action: "stop_all", confirm: true })

在底层，每次调用都会经过相同的请求流程：通过 Zod 验证输入、使用支持重试的 HTTP 客户端、屏蔽敏感信息，并返回带有恢复提示的结构化错误封装——这样 Agent 就能优雅地处理失败，而不是盲目猜测。

说明

这是一个面向自行运行 Coolify 实例用户的社区项目。本项目与 Coolify Labs 无关，也未获其认可。

🆚 为什么选择 awesome-coolify-mcp

常见的无它配置	使用 awesome-coolify-mcp
多个功能重叠的社区 MCP 工具，每个都有自己的架构	一个服务，一套一致的架构
针对每种资源提供数十个细粒度的单一用途工具	通过一致的 action 判别器提供 19 个工具
Agent 只能靠猜测理解的临时错误字符串	结构化错误代码（COOLIFY_401、COOLIFY_404……）+ 机器可读的恢复提示
密钥可能直接泄露到 Agent 上下文中	默认屏蔽密钥 + 对破坏性操作设置确认关卡
需要从一大堆原始 JSON 中查找变更内容	针对大模型上下文窗口优化的有界分页视图

目前，已发布的功能涵盖第 2 天运维和基础设施创建：验证连接、发现服务器群、部署并监控构建、检查有界日志、诊断事件、执行有确认关卡的紧急运维，以及管理应用、服务、数据库、SSH 密钥、服务器、项目、环境、备份和环境变量。

---

✨ 功能

• 19 个基于 action 的工具 — 调用 application({ action: "deploy", uuid })，无需在数十个细粒度工具名称中查找。已注册的工具包括 system、meta、resource、diagnose、application、emergency、deployment、service、database、private_key、instance、manifest、server、project、environment、docs、recipe、setup 和 intelligence。
• 多实例注册表与路由 — 通过 instance 工具，将你拥有的每个 Coolify 实例注册到 ~/.coolify-mcp/instances.json；每次调用时解析凭据，不会发生跨实例泄露。
• 兼容 Coolify Cloud — 使用 instance({ action: "cloud-info" }) 获取本地发现、团队范围的令牌，以及结构化的云错误代码（COOLIFY_CLOUD_FORBIDDEN、COOLIFY_CLOUD_UNSUPPORTED）。
• 本地清单缓存 — 通过 manifest({ action: "sync" }) 同步 .coolify/manifest.json，在修改应用／服务／数据库时尽力自动触发钩子，并在缓存过期时返回 _meta.manifestWarning。
• 服务品牌标识 — 通过 serverInfo.icons 设置 MCP 列表图标（来自 docs/assets/ 的内嵌数据 URI 和 jsDelivr CDN 条目）。
• 贴近真实事件的运维工作流 — 使用一次 system.infrastructure_overview 调用查看整体情况；只记得名称或域名时使用模糊匹配 resource.find；有明确的可疑对象时使用 diagnose.app / diagnose.server；只知道整个服务器群中 有问题 时使用 diagnose.scan。
• Agent 可驱动的部署生命周期 — 启动／停止／重启、强制重新构建、使用有界退避的 deployment.watch、用于构建的 deployment.logs、有界的 application.logs，以及带空闲／总超时的运行时跟踪。
• 完整的工作负载 CRUD — 创建、检查、更新、删除并操作应用、服务和数据库；使用 service.list-types 发现可实时使用的一键式 ID。
• 配方与引导式设置 — 创建 Git 应用、应用加数据库堆栈和一键式服务；运行 setup.preflight、setup.wire 或 setup.resume；安装四个匹配的 IDE 工作流技能。
• 默认安全，而非依赖惯例 — 紧急变更必须显式设置 confirm: true；敏感密钥（password、token、secret、private、env）默认显示为 ***，只有选择使用 reveal: true 才会显示。
• Agent 友好的故障处理 — 每个错误都以可解析的结构返回，包含 code、面向用户的 message 和 recoveryHints；临时网络／429／5xx 错误会自动使用指数退避重试。
• 开箱即用，广泛支持客户端 — 支持 Cursor、VS Code / GitHub Copilot、Claude Desktop、Claude Code、Windsurf 等 15 多种客户端，可通过安装配置器进行安装。

---

🏗️ 工作原理

MCP client (Cursor / Claude / VS Code / …)
        │  stdio MCP
        ▼
awesome-coolify-mcp  (19 tools + action discriminator)
        │  optional ~/.coolify-mcp/instances.json resolution
        │  HTTPS + Bearer token
        ▼
Coolify REST API 4.1.x  (servers · projects · applications · services · databases)

服务本身刻意保持简单：它不保留任何长期状态，也绝不会触碰 IDE 的配置文件。你的 MCP 宿主（Cursor、Claude、VS Code 等）通过 MCP 配置的 env 块注入 COOLIFY_URL 和 COOLIFY_TOKEN，或者你也可以通过 instance 工具在 ~/.coolify-mcp/instances.json 中注册命名实例。进程从环境变量（或注册表）中读取凭据，并通过 HTTPS 将经过身份验证的请求转发到你的 Coolify 实例。

---

🚀 快速开始

先决条件

• Node.js 24+（Active LTS；CI 使用 Node 24）
• 一个运行 4.1.x 的可自托管 Coolify 实例
• Coolify 的 API 令牌 → Keys & Tokens（授权文档）

通过 npx 直接运行，无需全局安装：

npx -y awesome-coolify-mcp

在 MCP 宿主中配置这两个必需的环境变量（有关每个客户端的配置，请参阅安装）。连接后，最简单的冒烟测试如下：

meta({ action: "version" })                       // server identity — no Coolify call
system({ action: "verify" })                      // authenticate + connectivity check
system({ action: "infrastructure_overview" })     // servers, projects, apps, services, DBs at a glance

说明

**多实例用户：**先使用 instance({ action: "add", name, url, token }) 注册每个 Coolify 实例，然后调用 system({ action: "verify" })。单实例配置可以跳过注册表，改为在 MCP 环境变量中使用 COOLIFY_URL / COOLIFY_TOKEN。

重要

紧急操作（stop_all、redeploy_project、restart_project）需要 confirm: true。请先不要传入 confirm 来调用——你会获得 would_affect 预览，且不会执行任何变更。只有确实需要获取明文密钥时，才传入 reveal: true。

---

📦 安装

有三种支持程度相同的方式——选择最适合你工作流的一种。

1. 一键深度链接

如果你已经准备好 Coolify URL 和令牌，这是最合适的方式。占位凭据也可以正常使用——系统会提示你填写，或者你可以之后再替换。

  

这些链接的工作原理（点击展开）

两款编辑器都实现了协议处理程序，可直接从 URL 读取 JSON 服务配置：

客户端	方案	编码
Cursor	cursor://anysphere.cursor-deeplink/mcp/install?name=…&config=…（也提供 https://cursor.com/en/install-mcp?… 链接，方便访问落地页）	config 是经过 base64 编码的 JSON
VS Code / Copilot	vscode:mcp/install?name=…&config=…	config 是经过 URL 编码的 JSON

点击按钮会打开编辑器，显示即将添加的服务，并允许你在确认前查看或编辑命令和环境变量——不会在你不知情的情况下安装任何内容。

2. 安装配置器（GitHub Pages）

使用**浏览器配置器**填写真实的 COOLIFY_URL / COOLIFY_TOKEN，并生成适用于你所用客户端、可直接粘贴的代码片段——具体格式为 JSON、TOML 或 YAML，取决于客户端的要求。

所有操作都在浏览器客户端完成。你的令牌绝不会发送到后端、记录日志，或存储在你粘贴配置的文件之外的任何地方。

3. 手动配置 MCP

将以下内容粘贴到主机的 MCP 配置文件中。Cursor 示例（全局配置使用 ~/.cursor/mcp.json，项目配置使用 .cursor/mcp.json）：

{
  "mcpServers": {
    "awesome-coolify-mcp": {
      "command": "npx",
      "args": ["-y", "awesome-coolify-mcp"],
      "env": {
        "COOLIFY_URL": "https://coolify.example.com",
        "COOLIFY_TOKEN": "YOUR_COOLIFY_API_TOKEN",
        "COOLIFY_VERIFY_SSL": "true",
        "COOLIFY_MCP_LOG": "info"
      }
    }
  }
}

你也可以在 docs/mcp.example.json 找到现成的复制粘贴模板。

提示

使用 Coolify Cloud？请生成团队范围的令牌，并按照 docs/en/cloud.md 中的步骤配置注册表。

IDE 技能（Cursor、Claude Code、Codex）

为 Cursor、Claude Code 和 Codex 安装 Coolify 工作流技能：

npx skills add clezcoding/awesome-coolify -a cursor -a claude-code -a codex

安装 MCP 后，运行 setup({ action: "preflight" })，或参阅**设置指南**，了解 gh 预检、项目关联和全新环境配置。

---

🖥️ 支持的客户端

客户端	配置位置	说明
Cursor	~/.cursor/mcp.json	一键深层链接或手动配置 JSON
VS Code / GitHub Copilot	.vscode/mcp.json	原生 inputs 提示词用于输入 URL/token — 文件中不会包含明文
Claude Desktop	claude_desktop_config.json	目前使用手动配置 JSON 或配置器输出
Claude Code	~/.claude.json 或 .mcp.json	通过 npx -y awesome-coolify-mcp 使用 stdio
Windsurf	~/.codeium/windsurf/mcp_config.json	使用与 Cursor 相同的 npx + env 模式

安装配置器 支持的客户端范围更广 — 包括 OpenCode、Codex CLI、Gemini CLI、Cline、Kilo Code、Goose、LM Studio、Hermes Agent、Kimi Code、Google Antigravity、OpenClaw 等 — 并为每种客户端提供正确的配置格式。

说明

Claude Desktop 目前使用手动配置 JSON 或配置器输出。

---

🔐 环境变量

变量	必填	默认值	说明
COOLIFY_URL	是*	—	Coolify 基础 URL，末尾不带斜杠 — 例如 https://coolify.example.com
COOLIFY_TOKEN	是*	—	Bearer API 令牌，限定为你的团队
COOLIFY_VERIFY_SSL	否	true	仅在本地/开发实例使用自签名证书时设为 false
COOLIFY_MCP_LOG	否	info	日志详细程度：debug · info · error

凭据从进程环境（IDE 的 MCP env 块）或直接运行 CLI 时使用的可选本地 .env 文件中读取。它们绝不会在工具响应中回显。

说明

使用多实例注册表（~/.coolify-mcp/instances.json）时，COOLIFY_URL 和 COOLIFY_TOKEN 变为可选 — instance 工具会在每次调用时解析凭据。对于单实例设置，环境变量仍是最简单的方式。

---

☁️ Coolify Cloud

awesome-coolify-mcp 可通过相同的 19 个工具 与 Coolify Cloud 配合使用 — 团队限定的令牌、结构化云错误代码（COOLIFY_CLOUD_FORBIDDEN、COOLIFY_CLOUD_UNSUPPORTED），以及用于发现的本地 instance 操作 cloud-info。

首次使用 Cloud 会话前，运行 instance({ action: "cloud-info" }) — 它会返回 isCloud、解析后的 url、凭据 source（registry | env | infer）、knownLimits 和文档链接。不会调用实时 API。

完整设置、冒烟测试和已知限制 → docs/en/cloud.md

---

💬 MCP 提示词

六个参数化工作流提示词会返回编号步骤指南（正文为英文），用于编排现有工具。大多数参数均为可选 — 无需预填即可打开任何提示词。

提示词	参数（除非另有说明，均为可选）	用途
deploy	instance?、uuid?、force?	部署应用并监控，直到状态进入终止状态
diagnose	instance?、uuid?	调查应用、服务器或整个实例群的问题（包含 diagnose.analyze）
new-project	instance?、name?、server_uuid?	创建项目、环境，并可选择关联服务器
incident	instance?、uuid?、project_uuid?	使用 diagnose.analyze、日志、重启或紧急重新部署进行事件分诊
rollback	instance?、uuid?、name?	预览后再确认执行 deployment.rollback（暂停，等待人工批准）
maintenance-window	instance?、uuid?、resource_type	使用现有的需确认变更操作引导变更窗口

提示词处理器不会从磁盘读取 .coolify/manifest.json — 它们会引导 Agent 从清单中解析 UUID，或询问用户。操作手册绝不会自动设置 confirm: true。

---

🧰 工具参考

每个领域都通过一个 MCP 工具公开，并使用 action 判别字段，因此 Agent 的工具列表保持简短，同时能力范围广泛。

system({ action: "health" })
application({ action: "deploy", uuid: "<app-uuid>", wait: false })
deployment({ action: "watch", deployment_uuid: "<deployment_uuid>", timeout: 300 })
emergency({ action: "stop_all", confirm: true })

🖥️ system — 连接与概览

每次会话中的首次调用：Coolify 是否可访问？当前资源群组是什么状况？

Action	Purpose
health	验证 Coolify API 是否可访问
version	Coolify 实例的版本字符串
verify	进行身份验证；一次调用即可返回连接状态和版本
infrastructure_overview	汇总服务器、项目、应用、服务和数据库的数量

🏷️ meta — 服务端身份

Action	Purpose
version	awesome-coolify-mcp 自身的包名和 semver — 不会调用 Coolify

🔎 resource — 发现资源

当你大致知道要找什么，但不知道它的确切 UUID 时使用。

Action	Purpose
list	以摘要形式列出应用、服务和数据库，并提供分页 _meta
find	按名称、域名或 IP 对服务器和资源进行模糊搜索 — 按相关度排序，最多返回 10 个结果

🩺 diagnose — 调查问题

当你觉得某些地方不太对劲，但还不知道具体问题时，可以使用此工具。

Action	Purpose
app	应用状态、运行状况、环境变量数量和近期部署
server	服务器资源、域名和可访问性
scan	按严重性分组显示全体资源群组的问题 — 相当于“哪里着火了”按钮
logs	解析应用，返回问题排查所需的上下文，并可选择包含有范围限制的运行时或部署日志
analyze	Log Brain — 基于规则对运行时日志（以及可选的构建日志）进行模式排查；仅提供建议（crash_loop、OOM 等）

🚀 application — 应用操作

Action	Purpose
get	获取应用的详细配置
start / stop / restart	控制容器生命周期
deploy	触发部署，可选使用 force 重新构建；使用 wait: false + deployment.watch（推荐），或使用旧版 wait: true 轮询
logs	获取有范围限制的运行时日志，或在空闲和总超时时间限制内以跟进模式获取日志
envs:list / envs:get	列出或获取环境变量（除非设置 reveal: true，否则值会显示为 ***）
envs:create / envs:update	创建或更新单个环境变量（支持 is_preview、is_literal、is_multiline、is_shown_once）
envs:delete	删除一个环境变量 — 需要 confirm: true
envs:bulk-update	一次性修补多个环境变量 — 需要 confirm: true
envs:sync	对本地 .env 文件或内联内容进行差异比较并应用更改 — 仅适用于应用；参见资源环境变量
envs:promote	比较并提升同一 Coolify 实例中两个应用之间的环境变量（产品名称：env.promote）；默认预览 — 参见资源环境变量

📈 deployment — 部署跟踪

Action	Purpose
list	列出指定应用的部署
get	获取某次部署的状态、提交和时间信息
watch	以有范围限制的超时、退避和抖动进行轮询，直至部署进入终态
cancel	安全取消正在进行的部署
logs	按部署 UUID 获取有范围限制的部署构建日志，或获取某个应用最近一次部署的日志
preflight	仅提供建议且只读的部署风险检查：instance_health、env_completeness、recent_deployment_failures、dns_readiness → risk_score / risk_level；环境变量值会被屏蔽；不执行实时 DNS 探测
rollback	须经确认：当最新部署已处于 finished 状态时，恢复到之前成功的 finished 部署；如果仅有一次成功部署，则返回 COOLIFY_ROLLBACK_UNAVAILABLE 错误 — git 应用通过 updateApplication 固定 git_commit_sha，然后调用 triggerDeploy；不带 confirm: true 时仅预览

🛡️ 部署防护（preflight + rollback）

操作	安全性
preflight	只读——绝不会调用部署／变更 API；advisory: true；当风险严重或部署正在进行时，blocking
rollback	两步操作，类似紧急操作：省略 confirm → COOLIFY_CONFIRM_REQUIRED + rollback_target 预览（目标是上一次成功的 finished 部署；若当前版本已完成，则不是当前版本）；confirm: true → 组合执行固定版本 + 部署（Coolify 没有专用的回滚 REST 端点）

deployment({ action: "preflight", uuid: "<app-uuid>" })
// risk acceptable → follow recommended_actions to application.deploy
deployment({ action: "rollback", uuid: "<app-uuid>" }) // preview
deployment({ action: "rollback", uuid: "<app-uuid>", confirm: true, wait: true })

⏱️ 监视 — 有界部署监控

调用 application.deploy 并设置 wait: false 后，调用 deployment.watch——不要手动循环调用 deployment.get。

行为	详情
默认超时	300 秒
轮询间隔	从 3s 开始，采用等抖动退避，最多 30s
超时恢复	使用相同的 deployment_uuid 再次调用 deployment.watch（对于耗时较长的构建，请调高 timeout）
失败／已取消	工具会返回明确的错误——不要将其视为成功
旧版方式	application.deploy wait:true 仍然可用，但仅用于向后兼容；建议使用 watch

application({ action: "deploy", uuid: "<app-uuid>", wait: false })
deployment({ action: "watch", deployment_uuid: "<deployment_uuid>", timeout: 300 })

随附的 IDE 技能包使用相同的有界监视流程，并说明了超时恢复方法。

🧩 service / database — 辅助服务生命周期

工具	操作
service	get、start、stop、restart、deploy、create（一键类型 XOR compose）、update、delete、delete_preview、envs:list、envs:get、envs:create、envs:update、envs:delete、envs:bulk-update
database	get、start、stop、restart、create（8 种引擎）、update、delete、delete_preview、envs:list、envs:get、envs:create、envs:update、envs:delete、envs:bulk-update、backup:create、backup:list、backup:update、backup:delete、backup:now、backup:history

🍳 recipe — 多资源编排

通过一次 MCP 调用即可搭建常见工作负载模式——应用与数据库连接、Git 应用，或经过验证的一键服务。

操作	用途
create-git-app	创建由 Git 提供支持的应用，并在本地检测 build_pack（通过 Dockerfile / Dockerfile.* glob）
create-app-db	创建数据库和应用，并在两者之间配置 DATABASE_URL（或自定义 env_key）
create-one-click	创建一键服务前，根据实时服务模板目录验证 type
recommend	根据实时服务模板目录提供建议性技术栈推荐——绝不创建资源

安全性： Recipe 创建属于主动操作——无需确认。没有试运行／预览。部分失败时不会自动回滚；已创建的 UUID 会在 error.data 中返回。连接字符串会被遮蔽，除非设置 reveal: true。recommend 为只读／建议性操作。

recipe({ action: "create-git-app", server_uuid, git_repository, git_branch, repo_path: "/path/to/repo" })
recipe({ action: "create-app-db", server_uuid, app_name, db_name, db_engine: "postgresql" })
recipe({ action: "create-one-click", server_uuid, type: "gitea" })
recipe({ action: "recommend", stack: "Next.js + Postgres" })

在调用 create-one-click 前，也可使用 service.list-types 查找有效的一键类型 ID。

🌱 资源环境变量（envs:*）

通过现有领域工具上的 envs:* 操作，管理应用、服务和数据库的 Coolify 运行时配置——无需单独的 env MCP 工具。

工具	envs:* 操作	备注
application	envs:list、envs:get、envs:create、envs:update、envs:delete、envs:bulk-update、envs:sync、envs:promote	唯一支持本地 .env 同步和跨应用环境变量提升的工具
service	envs:list、envs:get、envs:create、envs:update、envs:delete、envs:bulk-update	不支持同步——使用 application 进行 .env 差异比较和应用
database	envs:list、envs:get、envs:create、envs:update、envs:delete、envs:bulk-update	数据库环境变量不支持 is_preview（Coolify OpenAPI 的缺口）

确认门槛： 三种工具上的 envs:delete 和 envs:bulk-update 均始终要求设置 confirm: true。仅对 application 而言，应用更改时（dry_run: false，默认值）或设置 prune: true 时，envs:sync 要求设置 confirm: true。应用更改时（dry_run: false），envs:promote 要求设置 confirm: true。

显示策略： 环境变量值默认显示为 ***。只有在人类明确要求以明文显示后，才传入 reveal: true——Agent 不得自动设置 reveal: true。

envs:sync 语义（仅限 application）： 必须且只能提供 env_file（本地路径）或 env_content（内联 .env 文本）其中一项。dry_run: true 会返回差异（added、updated、unchanged、removed，以及可选的 conflicts），且不会写入 API；默认的 dry_run: false 会应用更改。仅当设置 prune: true 时，才会删除本地缺失的远程键（同时也要求设置 confirm: true）。本地值与远程值不同时，在询问人类后，将 conflict_policy 设为 overwrite、keep_remote 或 abort——存在冲突却未设置策略时，应用更改会返回 COOLIFY_CONFIRM_REQUIRED。

envs:promote 语义（仅限 application，同一实例）： 产品文档中可能称其为 env.promote；实际实现的操作是 application.envs:promote。比较 source_uuid 和 target_uuid 的环境变量（同一 Coolify 实例中的两个应用——不会跨实例分发）。默认的 dry_run: true 会返回预览分类（only_in_source、only_in_target、value_mismatches），以及包含后续工具/操作提示的结构化 promotion_suggestions；除非设置 reveal: true，否则值会被隐藏。将变量复制到目标应用时，必须设置 confirm: true。默认的 conflict_policy 为 keep_remote——目标应用中值不匹配的键会被跳过，除非人类选择 overwrite 或 abort。

application({ action: "envs:list", uuid: "<app-uuid>" })
application({ action: "envs:sync", uuid: "<app-uuid>", env_file: "./.env", dry_run: true })
application({ action: "envs:sync", uuid: "<app-uuid>", env_content: "API_KEY=EXAMPLE_VALUE\n", confirm: true, conflict_policy: "overwrite" })
application({ action: "envs:promote", source_uuid: "<source-app-uuid>", target_uuid: "<target-app-uuid>", dry_run: true })
application({ action: "envs:promote", source_uuid: "<source-app-uuid>", target_uuid: "<target-app-uuid>", dry_run: false, confirm: true, conflict_policy: "keep_remote" })

💾 数据库备份（backup:*）

在现有的 database 工具上配置、列出、更新、删除和触发备份计划，并检查执行历史记录。无需单独的备份 MCP 工具。

操作	用途
backup:create	创建备份计划（必须指定频率；可选 S3、保留期限、backup_now: true）
backup:list	列出数据库的备份计划
backup:update	更新计划字段（频率、保留期限、S3 标志）
backup:delete	移除计划 — 需要 confirm: true
backup:now	立即触发一次备份运行
backup:history	列出计划的执行记录（状态、时间戳、大小）

**父级标识：**所有备份操作都需要通过 uuid 或 name 指定父级数据库。针对计划的操作（backup:update、backup:delete、backup:now、backup:history）还需要 scheduled_backup_uuid。

确认门控：backup:delete 需要 confirm: true，否则会返回 COOLIFY_CONFIRM_REQUIRED。delete_s3 默认值为 false（仅删除配置）。当 delete_s3: true 时，删除仍需要 confirm: true — 清除 S3 资源会被视为破坏性操作。

频率（陷阱 1）：backup:create 接受 OpenAPI 命名预设（every_minute、hourly、daily、weekly、monthly、yearly）或 cron 表达式。backup:update 仅接受预设 — 更新时传入 cron 会返回 COOLIFY_VALIDATION_ERROR。

**backup:now 语义：**对计划执行 Coolify PATCH，并传入 { backup_now: true } — 没有单独的触发端点。需要 scheduled_backup_uuid。

**显示策略：**备份配置响应中的 S3 相关凭据默认会以 *** 遮盖。仅在人类明确要求以明文显示后才传入 reveal: true — Agent 不得自动设置 reveal: true。

**不在范围内（v2.x+）：**此版本不支持删除备份执行记录、从备份恢复/导入，以及 S3 存储目标的 CRUD 操作。

database({ action: "backup:list", uuid: "<db-uuid>" })
database({ action: "backup:create", uuid: "<db-uuid>", frequency: "daily", save_s3: false })
database({ action: "backup:now", uuid: "<db-uuid>", scheduled_backup_uuid: "<schedule-uuid>" })
database({ action: "backup:delete", uuid: "<db-uuid>", scheduled_backup_uuid: "<schedule-uuid>", confirm: true })

🔑 private_key — SSH 密钥 CRUD

管理 Coolify 私钥，PEM 内容默认会被遮盖。

操作	用途
list / get	列出或获取密钥（除非设置 reveal: true，否则会遮盖 PEM）
create / update	添加或轮换 SSH 密钥
delete / delete_preview	移除密钥，或在删除前预览其依赖项

🖧 server — 服务 CRUD 与验证

操作	用途
get	服务详情、域名和可访问性
create / update	注册或重新配置服务
validate	触发 Coolify 的服务验证检查
delete / delete_preview	移除服务，或先预览其依赖项

📁 project — 项目 CRUD

操作	用途
list / get	查找或检查项目
create / update	创建或重命名项目
delete / delete_preview	删除项目，或先预览影响范围

🌍 environment — 环境 CRUD

操作	用途
list / get	列出或检查项目内的环境
create	向项目添加新环境
delete / delete_preview	移除环境，或先预览其依赖项

📚 docs — 离线指南

操作	用途
search	搜索捆绑的精选 Coolify 故障排除索引 — 不会实时抓取网页，因此可离线使用，也不能用作外部抓取向量

🚨 emergency — 高影响运维操作（需门控）

仅在确有需要时使用 — 以下每项操作都设有确认门控。

操作	用途
stop_all	停止整个集群中所有正在运行的应用 — 需要 confirm: true
redeploy_project	重新部署项目中的所有应用 — 需要 confirm: true
restart_project	重启项目中的所有应用 — 需要 confirm: true

🗂️ instance — 多实例注册表

在 ~/.coolify-mcp/instances.json 中管理已命名的 Coolify 实例。按调用解析凭据，不会发生跨实例泄漏。

操作	用途
list	列出已注册的实例（令牌已遮蔽）
get	按名称获取一个实例
add	注册新实例（name、url、token，以及可选的 type: "cloud"）
update	轮换现有实例的 URL 或令牌
delete	移除实例 — 需要 confirm: true
set-default	为未显式指定 instance 参数的操作设置默认实例
import-env	选择启用：将进程环境中的 COOLIFY_URL 和 COOLIFY_TOKEN 复制到注册表
cloud-info	本地 Cloud 发现 — isCloud、url、source、knownLimits、文档链接（不调用 API）

instance({ action: "add", name: "prod", url: "https://coolify.example.com", token: "<token>" })
instance({ action: "list" })
instance({ action: "cloud-info" })

📜 manifest — 本地缓存

读取／写入／同步 .coolify/manifest.json — 工作区缓存，并非事实来源。UUID 冲突时以远程数据为准。

操作	用途
get	读取本地清单文件
upsert	将项目／服务器／资源合并到缓存中
set	替换清单的一个部分
remove	移除缓存的资源条目
clear	清空清单 — 需要 confirm: true
sync	根据实时 Coolify API 协调缓存（可选 dry_run，prune 需要 confirm）
diff	非破坏性差异报告 — 始终可以安全运行
audit	只读／建议性 漂移审计：包含带严重性标签的 findings[]，并提供结构化修复提示（下一步调用哪个工具／操作）；可选的 diff_support 详情 — 不会修改清单或实时状态

manifest({ action: "sync", dry_run: true })
manifest({ action: "diff" })
manifest({ action: "audit" })

说明

manifest.audit 会比较指定实例范围内的本地 .coolify/manifest.json 与实时 Coolify 资源清单。审计结果会列出后续操作，例如 manifest.sync 或 manifest.upsert — 这些提示仅供参考；不会自动修复。若要查看原始结构协调报告，请继续使用 manifest.diff。 尽力而为的自动钩子会在应用／服务／DB 修改后更新清单。其他位置出现过期 UUID 的 404 时，会显示 _meta.manifestWarning — 运行 manifest({ action: "sync" }) 进行协调。

🧭 setup — 引导式项目配置

操作	用途
preflight	检查 GitHub CLI 和工作区前置条件，不更改项目
wire	关联现有工作负载或配置全新项目，并可选择执行域名、环境变量同步、配方、清单和部署监视步骤
resume	在身份验证或其他可恢复的前置条件满足后，继续已暂停的配置

wire 绝不会自动推送。若缺少 gh 身份验证，配置流程会妥善暂停，并从已完成的步骤继续。

🎨 品牌标识（serverInfo.icons）

MCP 服务会在 initialize 中通过嵌入式 PNG data URI（主要方式）和 jsDelivr CDN URL 提供 mcp-icon-192.png 与 favicon-32.png 图标。Cursor 仍可能显示字母占位图 — 请参阅维护者验证记录。不会调用 Coolify API。

---

🛡️ 安全模型

确认关卡

破坏性紧急操作遵循严格的两步模式：

1. 调用时省略 confirm 或设为 false → 返回 would_affect 预览和错误代码 COOLIFY_CONFIRM_REQUIRED——不会修改任何内容。
2. 再次调用并设置 confirm: true → 实际执行操作。

常规应用／服务／数据库变更（启动、停止、部署……）不受此关卡限制——它们遵循 Coolify 自身的 API 语义，因为操作范围仅限单个资源，而非整个资源集。

环境变量： envs:delete 和 envs:bulk-update 在应用、服务和数据库上都要求设置 confirm: true。envs:sync 应用更改（dry_run: false）以及 envs:sync 设置 prune: true 时，仅在应用上要求设置 confirm: true。dry_run: true 的同步预览不会修改任何内容。envs:promote 应用更改（dry_run: false）时，在应用上要求设置 confirm: true；默认 conflict_policy 为 keep_remote。

漂移与修复（只读审计，预览优先的提升）： manifest.audit 仅提供参考——它不会写入清单或实时状态。application.envs:promote（产品名称 env.promote）默认会先预览；除非设置 reveal: true，否则值会保持遮蔽状态。每次调用都仅限于一个 Coolify 实例。

部署防护（提示性预检，回滚需确认）： deployment.preflight 为只读操作，并返回包含四个命名因素的 risk_score——不会探测外部 DNS／HTTP。deployment.rollback 修改前要求设置 confirm: true；Git 回滚会 PATCH 目标提交，然后 POST /deploy（这是 MCP 组合操作，并非 Coolify 回滚 API）。

秘密信息遮蔽

• 默认情况下，键名匹配 password、token、secret、private 或 env 的内容在工具输出中会显示为 ***。
• 仅在明确需要明文时传入 reveal: true——例如，要将环境变量复制到另一个系统。对任何 envs:* 调用设置 reveal: true 前，请先征求用户同意。
• 日志行正文不会被遮蔽。 请像处理其他敏感输出一样处理原始日志：不要将其粘贴到长期保存的 Agent 记忆或公开工单中。

警告

注册表文件（~/.coolify-mcp/instances.json）的目录权限为 0o700，文件权限为 0o600。除非明确传入 reveal: true，否则工具输出中绝不会回显令牌。

---

⚠️ 结构化错误与重试

每次 API 调用失败都会返回可解析的信封，供 Agent 判断，而不是原始堆栈跟踪：

{
  "code": "COOLIFY_401",
  "message": "Unauthorized — invalid or expired API token",
  "recoveryHints": [
    "Verify the token in Coolify UI → Keys & Tokens",
    "Ensure the token has the required team permissions"
  ],
  "httpStatus": 401
}

代码	含义
COOLIFY_401	令牌无效或缺失
COOLIFY_404	未找到资源
COOLIFY_422	验证错误
COOLIFY_500	Coolify 服务端错误
COOLIFY_NETWORK	连接失败
COOLIFY_TIMEOUT	请求超时
COOLIFY_CONFIRM_REQUIRED	紧急操作预览——传入 confirm: true 以继续
COOLIFY_AMBIGUOUS_MATCH	名称匹配到多个资源——从排序列表中选择一个 UUID
COOLIFY_CLOUD_FORBIDDEN	Cloud 令牌或团队权限问题（HTTP 403）
COOLIFY_CLOUD_UNSUPPORTED	Coolify Cloud 上没有此端点（HTTP 404）

暂时性故障（HTTP 429、5xx 或网络错误）会自动重试，最多 3 次，并采用指数退避（1s → 2s → 4s）；重试失败后会将错误返回给 Agent。

---

💬 Agent 工作流示例

“我的 Coolify 能连上吗？我有哪些资源？”

system({ action: "verify" })
system({ action: "infrastructure_overview" })
resource({ action: "list" })

“找到 nginx 应用，部署它，然后给我看日志。”

resource({ action: "find", query: "nginx" })
application({ action: "deploy", uuid: "<uuid>", wait: false })
deployment({ action: "watch", deployment_uuid: "<deployment_uuid>", timeout: 300 })
application({ action: "logs", uuid: "<uuid>" })

“整个资源集好像出了问题。”

diagnose({ action: "scan" })
diagnose({ action: "app", uuid: "<suspect>" })
diagnose({ action: "server", uuid: "<server>" })

“紧急情况：停止所有内容，但先让我看看影响范围。”

emergency({ action: "stop_all" })                 // preview — would_affect, no mutation
emergency({ action: "stop_all", confirm: true })  // execute

“多实例：列出已注册的实例，并逐个验证。”

instance({ action: "list" })
system({ action: "verify" })

---

✅ 当前状态

版本 1.1.4 的软件包提供 19 个工具和 6 个用于 Coolify API 4.1.x 的 MCP 提示词：

能力	状态
验证连通性 + 基础设施概览	✅ 已发布
发现：resource.list / resource.find	✅ 已发布
诊断：应用、服务及全实例扫描 + 后续提示	✅ 已发布
Log Brain（diagnose.analyze）+ 操作手册（incident、rollback、maintenance-window）	✅ 已发布
部署生命周期：启动/停止/重启、部署时等待模式 + 强制重建	✅ 已发布
部署跟踪：列表 / 获取 / 取消	✅ 已发布
部署监控和有界构建日志	✅ 已发布
应用运行时日志、有界跟踪和 diagnose.logs	✅ 已发布
实例智能（intelligence.scorecard、graph、impact、janitor、cleanup）	✅ 已发布
漂移与修复（manifest.audit、application.envs:promote / env.promote）	✅ 已发布
部署防护（deployment.preflight、deployment.rollback）	✅ 已发布
应用、服务和数据库 CRUD	✅ 已发布
动态一键类型发现、配方和 recipe.recommend	✅ 已发布
设置向导和四种 IDE 工作流技能	✅ 已发布
紧急运维：全部停止、项目重新部署/重启，需通过确认门控	✅ 已发布
SSH 密钥 CRUD（private_key），并支持 PEM 脱敏	✅ 已发布
服务 CRUD + 验证（server）	✅ 已发布
项目与环境 CRUD（project、environment）	✅ 已发布
密钥脱敏，需明确选择 reveal 才会显示	✅ 已发布
结构化错误、恢复提示、自动重试	✅ 已发布
npm 分发 + 适用于 15+ 个客户端的安装配置器	✅ 已发布
多实例注册表（instance、instances.json）	✅ 已发布
Coolify Cloud 路径（cloud-info、团队范围的令牌）	✅ 已发布
本地清单同步（.coolify/manifest.json、自动钩子）	✅ 已发布
实时 UAT 测试框架（npm run uat:live）	✅ 已发布
通过 system.version 发现能力	✅ 已发布
通过 deployment.logs 获取部署构建日志	✅ 已发布

能力发现与构建日志： system({ action: "version" }) 会返回 coolifyVersion（取代旧版 version 字段）、mcpVersion，以及包含 Coolify 4.1.2 功能标志的 capabilities 映射。若要通过一次调用完成应用分诊 + 有界运行时日志尾部，请使用 diagnose({ action: "logs", mode: "full", uuid: "..." }) — 检查 capabilities.diagnose_logs。若要进行 Log Brain 模式分诊，请使用 diagnose({ action: "analyze", uuid: "..." }) — 检查 capabilities.diagnose_analyze。若要根据实时目录推荐参考性技术栈，请使用 recipe({ action: "recommend", stack: "..." }) — 检查 capabilities.recipe_recommend。若要查看实例健康状况、依赖关系图、影响以及清理器/清理功能，请使用 intelligence({ action: "scorecard" | "graph" | "impact" | "janitor" | "cleanup", ... }) — 检查 capabilities.intelligence_scorecard（以及同系列的 intelligence_* 键）；cleanup 需要 confirm: true。若要进行清单漂移审计和跨应用环境变量提升，请使用 manifest({ action: "audit" }) 和 application({ action: "envs:promote", source_uuid, target_uuid, ... }) — 检查 capabilities.manifest_audit 和 capabilities.envs_promote（这些是基于现有读取/环境变量 CRUD 构建的 MCP 组合功能，并非 Coolify 原生 REST 端点）。对于部署的构建日志，优先使用 deployment({ action: "logs", deployment_uuid: "..." })（也可使用 application_uuid 来解析最新部署）。为保持向后兼容，使用 deployment_uuid 的 application.logs 路径仍然有效。若要跟踪运行时日志，请使用 application({ action: "logs", uuid: "...", follow: true }) — MCP 会进行有界轮询，直到空闲或超时；请通过 system.version 检查 capabilities.application_logs_follow。

警告

Coolify 4.1.x 不提供稳定的服务或数据库日志端点。因此，本服务不会声称支持或注册服务/数据库日志操作。兼容的上游 API 可用之前，请使用应用运行时日志和部署构建日志。

---

🔮 即将推出

未来工作将遵循可验证的上游和仓库约束：

• 在兼容的 Coolify API 稳定可用后，添加服务/数据库日志。
• 在 docs/COVERAGE.md 中补齐有助于 Agent 工作流的 REST 映射。
• 只有在明确保证速率限制和凭据隔离的情况下，才重新考虑跨实例扇出。

这些边界不附带发布日期或兼容性承诺。具体需求请通过 GitHub Issues 提出。

---

🛠️ 本地开发

git clone https://github.com/clezcoding/awesome-coolify.git
cd awesome-coolify
pnpm install
pnpm run build    # tsup → dist/
pnpm test         # vitest
pnpm run dev      # watch mode

日志仅写入 stderr — stdout 专用于 MCP 协议。

维护者的发布流程（build → pack --dry-run → publish）记录在 CONTRIBUTING.md 中。

说明

维护者可以使用 npm run uat:live，针对真实的 Coolify 实例运行实时 UAT。前置条件和报告输出请参阅 CONTRIBUTING.md — Live UAT Harness — 请勿在此重复说明操作流程。

---

🔗 链接

资源	URL
安装配置器	clezcoding.github.io/awesome-coolify/install.html
安装首页	clezcoding.github.io/awesome-coolify/
MCP JSON 示例	docs/mcp.example.json
品牌素材	docs/assets/
Coolify	coolify.io
MCP 规范	modelcontextprotocol.io
问题与功能请求	GitHub Issues
贡献指南	CONTRIBUTING.md
更新日志	CHANGELOG.md
安全政策	SECURITY.md
许可证	MIT