Coolify MCP

coolify-mcp

适用于 Coolify API 的 MCP 服务——支持从零开始到生产环境的完整部署工作流。

面向 Coolify v4.3.10 API。类型和架构直接根据 Coolify 官方 OpenAPI 规范生成，因此工具输入始终与 API 实际接受的内容一致。

功能

• 完整部署工作流：从头开始创建项目、环境、服务器和应用
• 5 种应用类型：一个 createApplication 工具即可处理公共 git、GitHub App、Deploy Key、Dockerfile 和 Docker Image 来源；此外还可通过 createService 部署 Docker Compose（从 Coolify v4.1 开始，Compose 部署属于服务）
• 环境管理：完整支持环境变量的增删改查，并可屏蔽机密信息
• 部署控制：部署（可选择等待终态，并在失败时显示日志末尾内容）、启动、停止和重启应用
• 诊断：diagnoseApp 可通过 UUID、名称或域名查找应用，并汇总状态、近期部署、失败日志末尾内容、运行时日志和建议的后续操作
• 文档搜索：searchDocs 使用内置的本地索引对 Coolify 官方文档进行全文搜索，无需联网
• 安全性：写入保护、机密信息脱敏和 MCP 注解（readOnlyHint/destructiveHint），使客户端可以自动批准读取操作，并限制破坏性调用
• 接近完整的 API 覆盖：数据库（8 种引擎、备份、环境变量）、服务、存储、计划任务、团队、预览、服务器、SSH 密钥和 GitHub Apps
• 节省令牌：65 个工具的定义仅占用约 9k 个上下文令牌，并通过根据 Coolify OpenAPI 规范生成的架构进行严格的运行时验证

要求

• Node 18+
• Coolify API 令牌（在 Coolify 控制面板的 Settings > API 中获取）

安装

**Claude Desktop，一键安装：**从最新版本下载 coolify-mcp.mcpb，然后将其拖放到 Settings → Extensions。系统会提示你输入 Coolify URL 和令牌——无需安装 Node，也无需编辑 JSON。

通过 npm 安装：

npm install -g @fndchagas/coolify-mcp
# or
npx -y @fndchagas/coolify-mcp

快速开始

Claude Code CLI

claude mcp add coolify \
  --env COOLIFY_BASE_URL="https://coolify.example.com/api/v1" \
  --env COOLIFY_TOKEN="<token>" \
  -- npx -y @fndchagas/coolify-mcp

OpenAI Codex CLI

codex mcp add coolify \
  --env COOLIFY_BASE_URL="https://coolify.example.com/api/v1" \
  --env COOLIFY_TOKEN="<token>" \
  -- npx -y @fndchagas/coolify-mcp

或者编辑 ~/.codex/config.toml：

[mcp_servers.coolify]
command = "npx"
args = ["-y", "@fndchagas/coolify-mcp"]
env = { COOLIFY_BASE_URL = "https://coolify.example.com/api/v1", COOLIFY_TOKEN = "<token>" }

手动配置（~/.mcp.json）

{
  "mcpServers": {
    "coolify": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fndchagas/coolify-mcp"],
      "env": {
        "COOLIFY_BASE_URL": "https://coolify.example.com/api/v1",
        "COOLIFY_TOKEN": "<token>",
        "COOLIFY_ALLOW_WRITE": "true"
      }
    }
  }
}

环境变量

变量	默认值	描述
COOLIFY_BASE_URL	必填	Coolify API URL（例如：https://coolify.example.com/api/v1）
COOLIFY_TOKEN	必填	从 Coolify Settings > API 获取的 API 令牌
COOLIFY_ALLOW_WRITE	true	启用写入操作（创建、更新、删除、部署）
COOLIFY_STRICT_VERSION	false	API 版本不匹配时失败
COOLIFY_MCP_ELICITATION	on	设置为 off 可跳过破坏性删除操作的人工确认（适用于声明支持 elicitation 但未实现该功能的客户端）
MCP_TRANSPORT	stdio	传输方式：stdio、http、both
PORT	7331	HTTP 端口（使用 http 传输时）
MCP_HTTP_TOKEN	未设置	/mcp 请求所需的 Bearer 令牌（HTTP 传输）。设置此项后，默认绑定地址也会切换为 0.0.0.0
MCP_HTTP_HOST	127.0.0.1（设置令牌时为 0.0.0.0）	HTTP 传输绑定的接口。未设置令牌却绑定到回环地址以外的接口时，会记录醒目的警告

从零开始部署

使用此 MCP，你可以从头开始部署应用：

1. listProjects / createProject       → Get or create a project
2. listEnvironments / createEnvironment → Get or create an environment
3. listServers / createServer         → Get or create a server
4. listPrivateKeys / createPrivateKey → Get or create SSH keys (if needed)
5. createApplication (type: public)   → Create the application
6. applicationEnvs (action: upsert)   → Configure environment variables
7. deploy                             → Trigger deployment

工具参考

项目和环境

工具	描述	写入
listProjects	列出所有项目
createProject	创建新项目	✓
updateProject	更新项目名称/描述	✓
deleteProject	删除项目及其所有资源	✓
listEnvironments	列出项目中的环境
createEnvironment	创建新环境	✓

服务端和基础设施

工具	描述	写入
listServers	列出所有服务端
getServer	获取服务端详情
createServer	创建新服务端	✓
validateServer	验证服务端连接
listPrivateKeys	列出 SSH 私钥
createPrivateKey	创建新的 SSH 密钥	✓
listGithubApps	列出已配置的 GitHub Apps

应用 - 读取

工具	描述
listApplications	列出所有应用（默认显示摘要）
getApplication	获取应用详情（默认会屏蔽密钥）
getLogs	获取应用运行日志

应用 - 创建

工具	描述	写入
createApplication	创建应用；type 用于选择来源：public、private-github-app、private-deploy-key、dockerfile 或 dockerimage。较少用到的字段放在 extra 中，并按类型进行验证。	✓

Docker Compose 部署通过传入 docker_compose_raw 调用 createService 创建——从 Coolify v4.1 起，它们属于服务，而非应用。

应用 - 管理

工具	描述	写入
updateApplication	更新应用配置	✓
deleteApplication	删除应用	✓
startApplication	启动应用	✓
stopApplication	停止应用	✓
restartApplication	重启应用	✓

环境变量

工具	描述	写入
applicationEnvs	管理应用环境变量：列出（默认屏蔽）、创建、更新、按键执行 upsert、批量更新、删除	✓

数据库和服务的环境变量有各自的工具：databaseEnvs 和 serviceEnvs。

部署

工具	描述	写入
deploy	触发部署；wait: true 会轮询直至终端状态，并在失败时返回末尾日志	✓
diagnoseApp	按 UUID、名称或域名诊断应用：状态、最近的部署、失败日志末尾、运行时日志和提示
diagnoseServer	按 UUID、名称或 IP 诊断服务器：资源状态明细、域名和提示
listDeployments	列出正在运行的部署
getDeployment	获取部署状态和日志
listAppDeployments	列出应用的部署
cancelDeployment	取消正在运行的部署	✓

数据库

工具	描述	写入
listDatabases	列出所有数据库
getDatabase	获取数据库详情
createDatabase	创建数据库；type 用于选择引擎：postgresql、mysql、mariadb、mongodb、redis、keydb、dragonfly、clickhouse	✓
updateDatabase	更新数据库配置	✓
deleteDatabase	删除数据库（默认删除卷和配置）	✓
controlDatabase	启动、停止或重启数据库	✓
databaseBackups	管理备份计划和执行记录（list/create/update/delete/list_executions/delete_execution）	✓
databaseEnvs	管理数据库环境变量（list/create/update/bulk_update/delete）	✓

服务

工具	描述	写入
listServices	列出服务
getService	获取服务详情（默认遮蔽密钥）
createService	创建一键式服务或 Docker Compose 部署	✓
updateService	更新服务	✓
deleteService	删除服务	✓
controlService	启动、停止或重启服务	✓
serviceEnvs	管理服务环境变量（list/create/update/bulk_update/delete）	✓

存储、计划任务与预览

工具	描述	写入
storages	管理应用、数据库和服务的持久卷与文件挂载	✓
scheduledTasks	管理应用和服务的 cron 任务，包括执行历史记录	✓
deletePreview	按拉取请求 ID 删除预览部署	✓

团队、服务器与 Git

工具	描述	写入
teams	列出团队、获取当前团队并列出成员
updateServer	更新服务器配置	✓
deleteServer	删除服务器	✓
getServerResources	列出在服务器上运行的资源
getServerDomains	列出服务器上配置的域名
getPrivateKey	获取 SSH 密钥元数据（默认遮蔽密钥材料）
updatePrivateKey	更新 SSH 私钥	✓
deletePrivateKey	删除 SSH 私钥	✓
getGithubAppRepositories	列出 GitHub App 可访问的仓库
getGithubAppBranches	列出仓库的分支

批量操作

工具	描述	写入
getInfrastructureOverview	一次调用汇总服务器、项目、应用（状态明细）、数据库、服务和正在运行的部署
restartProjectApps	重启项目或环境中的所有应用（会请求确认）	✓
redeployProject	为项目或环境中的所有应用触发部署（会请求确认）	✓
stopAllApplications	紧急停止所有正在运行的应用，也可按项目停止（会请求确认并说明影响范围）	✓

其他

工具	描述
listResources	列出所有资源并支持筛选
searchDocs	对 Coolify 官方文档进行全文搜索（使用内置索引，不联网）
getHealth	检查 Coolify API 是否正常运行

安全功能

写入保护

禁用所有写入操作：

COOLIFY_ALLOW_WRITE=false

秘密信息屏蔽

• 默认屏蔽环境变量值
• 隐去数据库凭据
• 仅在必要时使用 showSecrets: true

HTTP 传输加固

HTTP 传输默认绑定到 127.0.0.1。若要将其公开到本地回环地址之外，请设置 MCP_HTTP_TOKEN——此后，对 /mcp 的每个请求都必须携带 Authorization: Bearer <token>（采用恒定时间校验）——绑定地址也会切换为 0.0.0.0（可使用 MCP_HTTP_HOST 覆盖）。若绑定到非本地回环地址却未设置令牌，系统会发出醒目的警告：任何能够访问该端口的人都可以控制你的 Coolify 实例。

删除操作前的人为确认

对于支持征询的 MCP 客户端（Claude Code、VS Code Copilot），删除项目、应用、数据库、服务、服务器或私钥前，系统会先要求你确认，并说明将会丢失什么。不支持征询的客户端行为与此前完全一致。拒绝、取消或超时都会中止调用；设置 COOLIFY_MCP_ELICITATION=off 可完全停用提示。

开发

git clone https://github.com/frndchagas/coolify-mcp.git
cd coolify-mcp
npm install
npm run dev

脚本

npm run dev            # Run in development mode
npm run build          # Build TypeScript
npm run generate       # Fetch the pinned OpenAPI spec and regenerate types

固定的 Coolify 版本

版本定义在 src/coolify/constants.ts 中。更新方法：

1. 编辑 src/coolify/constants.ts 中的 COOLIFY_VERSION
2. 运行 npm run generate

注册表列表

• MCP 注册表：io.github.frndchagas/coolify-mcp

MCP 客户端示例

HTTP 客户端

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'coolify-client', version: '1.0.0' });
const transport = new StreamableHTTPClientTransport(
  new URL('http://localhost:7331/mcp')
);

await client.connect(transport);

// List all applications
const apps = await client.callTool({
  name: 'listApplications',
  arguments: {},
});
console.log(apps.structuredContent);

// Deploy an application
const deploy = await client.callTool({
  name: 'deploy',
  arguments: { uuid: 'your-app-uuid' },
});
console.log(deploy.structuredContent);

await client.close();

Stdio 客户端

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = new Client({ name: 'coolify-client', version: '1.0.0' });
const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@fndchagas/coolify-mcp'],
  env: {
    COOLIFY_BASE_URL: 'https://coolify.example.com/api/v1',
    COOLIFY_TOKEN: '<token>',
  },
});

await client.connect(transport);

const result = await client.callTool({
  name: 'getApplication',
  arguments: { uuid: 'your-app-uuid' },
});
console.log(result.structuredContent);

await client.close();

许可证

MIT