Coolify Mcp

Coolify MCP 服务

通过 Claude、Cursor 或任何 MCP 客户端管理 Coolify：提供 46 个工具，用通俗语言部署、调试和运维可自托管的 PaaS。破坏性操作会先征求人工确认；密钥始终保持隐藏。

📖 coolify-mcp.stumason.dev · 工具参考 · 提示词和资源 · 远程 / HTTP 模式 · 集群 · Doctor · 安全与防护 · 变更日志

安装

你需要一个正在运行的 Coolify v4 实例和一个 API 令牌（Coolify → Keys & Tokens → API tokens）。选择以下三种方式之一来运行服务。

Claude Desktop，一键安装。 下载 coolify-mcp.mcpb，并将其拖到 Settings → Extensions 中。系统会提示你输入 Coolify URL 和令牌。无需安装 Node，也无需编辑 JSON。

在本地通过任何 MCP 客户端运行。 Claude Code：

claude mcp add coolify \
  -e COOLIFY_BASE_URL="https://your-coolify-instance.com" \
  -e COOLIFY_ACCESS_TOKEN="your-api-token" \
  -- npx @masonator/coolify-mcp@latest

Codex CLI 的操作相同，使用 codex mcp add 和 --env。对于 Cursor、Claude Desktop 或任何接受 JSON 配置的客户端：

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["-y", "@masonator/coolify-mcp"],
      "env": {
        "COOLIFY_BASE_URL": "https://your-coolify-instance.com",
        "COOLIFY_ACCESS_TOKEN": "your-api-token"
      }
    }
  }
}

作为 Coolify 内部的容器远程运行。 在管理的 Coolify 旁边部署此服务，并将 claude.ai、Claude Desktop 或 Claude Code 连接到 https://your-domain/mcp。Coolify 令牌保留在服务端；客户端通过 OAuth 2.1 进行身份验证。只需五分钟即可完成设置，详见 docs/http-mode.md。

然后运行 doctor

无论你采用哪种配置方式，都可以通过一条命令进行验证：

COOLIFY_BASE_URL="https://your-coolify-instance.com" COOLIFY_ACCESS_TOKEN="your-api-token" \
  npx @masonator/coolify-mcp doctor

它会检查配置中常见的问题（未展开的 ${VAR}、粘贴时带入的空格、重复的 /api/v1），确认 Coolify 可访问且未被 Cloudflare Access 登录页拦截，验证令牌已获接受且可以部署，并确认你的 Coolify 版本处于已测试范围内。每项检查失败时都会附带一行修复建议。脚本中可添加 --json。它绝不会打印密钥。每项检查的说明都在 doctor guide 中。

通过代理或 Cloudflare Access 访问

对于通用身份验证代理，可添加 --header "Key: Value" 参数（可重复添加）。对于 Cloudflare Access，请设置 CF_ACCESS_CLIENT_ID 和 CF_ACCESS_CLIENT_SECRET（Access 服务令牌）；无论本地模式还是远程模式，发往 Coolify 的每个请求都会携带这些信息。设置说明。

功能

每个工具都接受一个 action；不带参数运行工具即可查看它接受的内容。工具参考列出了完整表格。简而言之：

• 查明问题所在。 diagnose_app 和 diagnose_server 接受名称、域名、IP 或 UUID；find_issues 会扫描整个资源环境；logs 会读取任意容器的日志。
• 部署和回滚。 deploy 会等待最终状态，并在失败时返回日志末尾内容。使用 control 启动、停止或重启任何对象。
• 创建和销毁。 可操作应用、数据库（8 种引擎）、服务、项目和环境；使用 environments verify_app 在变更前确认绑定。
• 处理配置。 环境变量、存储、计划任务、备份、标签、私钥、GitHub 应用、云令牌。除非你指定一个确切的密钥，否则返回的密钥内容都会被屏蔽。
• 覆盖整个资源环境进行操作。 bulk_env_update、redeploy_project、stop_all_apps 均需经过人工确认，并说明影响范围。
• 使用 search_docs 搜索 Coolify 文档。

列表会返回 uuid/name/status 摘要，比原始 API 响应小 90–99%；get_* 工具会完整获取单个资源。整个工具列表约占用 8,900 个上下文令牌。

不只是工具，更有工作流

内置了三个以斜杠命令形式提供的提示词：troubleshoot_application、explain_failed_deploy 和 estate_health。选择一个，模型便会使用现有工具逐步执行工作流。两个资源 coolify://overview 和 coolify://application/{uuid} 可供客户端读取；两者都采用与每次工具调用相同的屏蔽机制，也都无法获取明文。未注册其工具的提示词不会显示，因此只读模式不会提供无法完成的操作。提示词和资源。

多个 Coolify 实例

除了默认配置外，将 COOLIFY_INSTANCES 设置为一个包含 { name, url, token } 的 JSON 数组。此后，每个工具都会接受可选的 instance 参数，list_instances 会报告已配置的实例，每项破坏性操作的确认信息都会注明目标实例。单实例安装的字节内容完全相同。一个服务器群组属于同一个信任域；为每个客户分别运行 Coolify 的代理机构应为每位客户运行一个服务器。服务器群组指南。

可安全用于生产环境

对于支持请求确认的客户端（Claude Code、VS Code Copilot），破坏性操作会在执行前停止，并在你自己的客户端中征求你的确认。在远程模式下，防护机制会在出现异常时默认拒绝操作。密钥会在 API 边界处被屏蔽，日志输出会被包装为不可信数据，防止遭到投毒的日志行发出指令；每次变更都会通过评估套件对这两项保障进行红队测试。详情。

适用于 Coolify v4.0 至 v4.3。已处理 v4.2 中从 GET 改为 POST 的变更，以及 v4.2 的密钥和 Member 角色限制；请参阅兼容性。

Coolify 自带的 MCP 服务，以及适合使用这个服务的场景

Coolify 自带内置于产品中的 MCP 服务。在 Settings → Advanced 中启用该服务（并按团队启用），将客户端指向 https://your-coolify/mcp，无需安装任何东西：它在实例内部运行，因此不会有第三方代码接触你的令牌。如果你只运行一个 Coolify，只有一个团队，而且主要是想向它提问，就用这个服务。这是最简单的方式，而且完全免费。

截至撰写本文时，Coolify 将其服务记录为只读，并计划添加写入操作。它发展很快，请查看 Coolify 文档，了解目前的进展。如果你更愿意编写脚本而不是对话，也可以使用官方 CLI。

这个服务适用于上述两者尚未覆盖的任务。

	Coolify 内置的 /mcp	官方 CLI	本服务
运行位置	Coolify 内部	你的 Shell	你的机器，或 Coolify 内部的容器
安装	无需安装	一个二进制文件	npx、一键安装的 Claude Desktop 扩展，或容器
传输方式	Streamable HTTP	不是 MCP 服务	stdio 和 HTTP，因此也适用于只支持 stdio 的客户端
Coolify 实例	一个	一次一个上下文	一个或多个；在舰队模式下，每个工具都需要传入 instance
写入操作	目前记录为只读	支持	支持
执行破坏性调用前	不适用	由你输入	在支持 elicitation 的客户端上暂停并向你确认，同时说明影响范围；在 HTTP 模式下则默认拒绝
出现故障时	不适用	Shell 退出代码	doctor 会指出原因和一行修复方法

一个大致的判断规则：只有一个实例，只想提出只读问题，且不想进行设置：使用 Coolify 自带的服务。编写脚本和 CI：使用 CLI。需要管理多个实例、希望写入操作先经过人工把关、使用只支持 stdio 的客户端，或想知道故障的_原因_：使用本服务。

还有其他第三方 Coolify MCP 服务。选择时，请考虑传输方式、单个连接需要访问的实例数量，以及删除操作执行前会发生什么。

示例提示词

Give me an overview of my infrastructure
Diagnose my shop.example.com app
Find any issues in my infrastructure
Deploy application {uuid} and wait for it to finish
Update the DATABASE_URL env var for application {uuid}
Restart all applications in project {uuid} on instance staging
How do I fix a 502 Bad Gateway error in Coolify?

开发

git clone https://github.com/StuMason/coolify-mcp.git
cd coolify-mcp && npm install
npm run build && npm test

COOLIFY_BASE_URL="https://your-coolify.com" COOLIFY_ACCESS_TOKEN="token" node dist/index.js

工具描述本身就是提示词，因此 evals/ 会衡量模型是否选择了正确的工具，以及攻击者控制的输出能否诱使模型行为异常；契约快照会对每个 PR 进行门控。请参阅 evals/README.md。欢迎贡献：CONTRIBUTING.md，以及 CLAUDE.md 中的架构和 API 易错点说明。

与我合作

我是 Stu Mason。我为代理机构、中小企业和企业构建 MCP 服务、AI 集成和 Agent 系统。本仓库展示了这些工作的实际成果。

• 为你的产品打造 MCP 服务。 让 Claude、Cursor 和所有其他 AI 客户端都能像使用这个服务一样，顺畅地接入你的 API。
• 从你自己的资料中获取答案。 让 AI 根据你的文档和数据作答，并提供依据，而不是胡乱猜测。还可以部署在你自己的服务器上。
• 让工作自动运行。 按计划运行任务，进行整理、检查和报告，并在任何内容发出前由人工审核。

如果你是代理机构，可以使用自己的品牌进行白标。如果某项工作不需要 AI，我会在有人为此付费之前说明。

📮 [email protected] · stumason.dev · coolify-mcp.stumason.dev

隐私政策

此服务不会收集你的任何信息。它没有遥测、分析功能，也不会向外发送数据，并且没有任何托管服务作为后端。

你的 Coolify API 令牌只会发送到你配置的实例，不会发送到其他地方。其他出站请求仅包括：从 coolify.io 单次刷新文档索引，该请求会携带缓存验证器，但不含凭据；以及在 HTTP 模式下，不带凭据地获取连接客户端自己的元数据文档。工具结果会发送到你自己的 MCP 客户端，后续如何处理由该客户端的隐私政策决定。审计日志会写入你自己的 stderr，且绝不会包含令牌值。

完整详情（包括每项说明在代码中的实现位置）请参阅 PRIVACY.md。

链接

• Coolify：此服务驱动的开源、可自托管 PaaS
• MCP Registry：登记名称为 io.github.StuMason/coolify
• laravel-coolify：通过仪表板、Artisan 命令和生成的 Dockerfile 将 Laravel 部署到 Coolify
• Model Context Protocol

MIT © Stu Mason。如果你觉得有用，请给仓库点个 ⭐。如果它帮你省下了一个晚上的时间，请我喝杯咖啡。