Coolify MCP Server：让 AI 助手接管你的自托管运维

作者：Stuart Mason

---

一、背景故事：运维的"最后一公里"困境

想象一个这样的场景：凌晨两点，你的自托管服务器上某应用突然告警，你不想打开终端、不想查文档，只想对 AI 说一句"帮我看看那台服务器有没有问题"。Coolify MCP Server 就是来解决这个问题的——它把 Coolify 自托管 PaaS 平台的全部能力，以 AI 助手能理解的方式封装成 42 个工具，让你在任何 MCP 兼容的 AI 界面里直接用自然语言管理基础设施。

Coolify 是一个开源的自托管 Heroku 替代方案，用户可以在自己的服务器上部署应用、数据库、私有 Git 仓库，支持 Docker 容器化部署、一键 SSL、负载均衡等功能。Coolify 的 API 非常完善，但传统的 API 调用需要编写代码、理解端点格式，门槛不低。而 Model Context Protocol（MCP）正是 Anthropic 提出的 AI 上下文协议，允许 AI 助手通过标准化的"工具"与外部系统交互。

作者 Stuart Mason（GitHub: StuMason）本身是 AI 应用开发者，专注于为机构和创业者提供 AI 产品交付服务。他开发这个 MCP Server 的核心理念是：让 DevOps 操作变得像聊天一样简单。

---

二、技术架构：四层模块化设计

coolify-mcp 的代码结构清晰，分为四个核心模块：

2.1 入口层（index.ts）

#!/usr/bin/env node

import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CoolifyMcpServer } from './lib/mcp-server.js';
import { parseHeaders } from './lib/parse-headers.js';

async function main(): Promise<void> {
  const customHeaders = parseHeaders(process.argv);
  const config: CoolifyConfig = {
    baseUrl: process.env.COOLIFY_BASE_URL || 'http://localhost:3000',
    accessToken: process.env.COOLIFY_ACCESS_TOKEN || '',
    customHeaders: Object.keys(customHeaders).length > 0 ? customHeaders : undefined,
  };
  const server = new CoolifyMcpServer(config);
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

入口层非常简洁，通过 StdioServerTransport 实现标准输入输出通信——这是 MCP 协议的经典传输模式，AI 客户端通过 stdin/stdout 与 MCP Server 交换 JSON-RPC 消息。环境变量配置 COOLIFY_BASE_URL 和 COOLIFY_ACCESS_TOKEN，也支持通过命令行参数传入自定义 HTTP 头。

2.2 MCP 服务器核心（mcp-server.ts）

这是项目最核心的文件，约 1916 行，定义了全部 42 个工具。每个工具通过 MCP SDK 的 server.addTool() 方法注册，接受 Zod schema 定义输入参数，返回 JSON 格式结果。

核心设计模式是操作参数化——同一个工具通过 action 参数切换不同操作（如 projects 工具同时支持 list/get/create/update/delete），而非为每个操作单独定义工具。这种设计将 token 消耗降低了 85%（从 43,000 降至 6,600），有效避免了 AI 上下文的上下文窗口耗尽问题。

// 典型工具注册模式
server.addTool({
  name: 'projects',
  description: 'List, get, create, update or delete projects',
  inputSchema: {
    type: 'object',
    properties: {
      action: { type: 'string', enum: ['list', 'get', 'create', 'update', 'delete'] },
      projectId: { type: 'string' },
      // ... 其他参数
    },
  },
  handler: async ({ action, projectId, ... }) => {
    // 统一处理逻辑
  }
});

2.3 Coolify API 客户端（coolify-client.ts）

封装了与 Coolify API 的所有 HTTP 通信逻辑，处理认证（Bearer Token）、分页、错误处理等。Coolify API 返回的数据结构复杂，包含服务器、项目、应用、数据库、服务等多种资源类型，客户端层负责将这些数据转换为 MCP 友好的格式。

2.4 文档搜索引擎（docs-search.ts）

利用 MiniSearch 全文搜索引擎在本地索引 Coolify 官方文档，支持 search_docs 工具进行语义搜索。这是解决"AI 不知道 Coolify 某个功能怎么用"问题的关键——不需要联网查询，直接在本地文档索引中检索。

---

三、42 个工具全景图

MCP Server 的工具覆盖了 Coolify 平台的全生命周期管理：

类别	工具数量	代表工具
基础设施	4	get_infrastructure_overview、system
诊断	3	diagnose_app、diagnose_server、find_issues
批量操作	4	restart_project_apps、bulk_env_update、stop_all_apps
服务器	5	list_servers、server_resources、server_domains
项目	1（含 CRUD）	projects
应用	2（含 CRUD）	list_applications、application_logs
数据库	2（含 8 种类型）	list_databases、database
服务	1（含 CRUD）	services
环境变量	1（含批量）	env_vars
存储	1	storages
定时任务	1	scheduled_tasks
部署	3	list_deployments、deploy、deployment
私有密钥	1	private_keys
GitHub Apps	1	github_apps
团队	1	teams
云凭证	1	cloud_tokens
Hetzner Cloud	1	hetzner
文档搜索	1	search_docs

---

四、部署与使用

4.1 安装方式

项目提供两种安装途径：

方式一：npm 全局安装（推荐）

npm install -g @masonator/coolify-mcp

方式二：Docker 部署

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json ./src ./
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev --ignore-scripts
COPY --from=builder /app/dist ./dist
ENTRYPOINT ["node", "dist/index.js"]

Docker 镜像采用多阶段构建，生产阶段仅安装生产依赖，最终镜像体积控制在合理范围内。

4.2 Claude Desktop 配置

在 claude_desktop_config.json 中添加：

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

4.3 前置要求

• Node.js >= 20
• 运行中的 Coolify 实例（测试版本 v4.0.0-beta.460）
• Coolify API 访问令牌（在 Coolify 设置 > API 中生成）

---

五、代码质量深度解析

5.1 测试覆盖

项目使用 Jest + ts-jest 进行测试，包含单元测试和集成测试。测试配置中使用了 jest-junit 生成覆盖率报告，@testPathIgnorePatterns=integration 区分了快速单元测试和慢速集成测试。值得关注的是，测试使用了 Node.js 实验性特性（NODE_OPTIONS=--experimental-vm-modules），这是 ESM 模块环境下运行 Jest 的标准配置。

5.2 代码规范

• ESLint + Prettier：完整的代码风格检查和格式化配置
• Husky + lint-staged：Git hooks 强制提交前检查
• markdownlint-cli2：README 文档质量检查
• Repomix：代码打包工具，用于 AI 可读的代码输出
• codecov：持续追踪测试覆盖率

5.3 依赖管理

依赖精简且质量高：

• @modelcontextprotocol/sdk（^1.23.0）：Anthropic 官方 MCP SDK
• zod（^4.3.5）：运行时类型验证
• minisearch（^7.2.0）：轻量级全文搜索

值得注意的是 package.json 中的 overrides 字段显式锁定了 15 个间接依赖版本，以应对供应链安全风险（如 handlebars、qs、hono 等历史漏洞高发库）。

5.4 安全考量

• MCP SDK 依赖链中的 ajv 被锁定到 ^8.20.0
• API 令牌通过环境变量注入，不硬编码
• 支持自定义 HTTP 头处理企业代理场景
• 包含 MseeP.ai 安全评估 badge

---

六、争议与局限

尽管 coolify-mcp 功能强大，但也存在一些需要注意的地方：

1. 自托管的局限性：该工具本质上是 Coolify 的"外壳"，需要有可用的 Coolify 实例。如果用户尚未部署 Coolify，或者 Coolify 实例不可达，MCP Server 无法独立工作。

2. 操作风险：通过 AI 执行服务器操作（删除数据库、重启服务等）存在误操作风险。虽然 MCP 工具提供了参数校验，但 AI 生成的参数仍需要人工二次确认。

3. 版本兼容性：项目文档显示测试基于 Coolify v4.0.0-beta.460，对其他版本（尤其是 v3.x）的兼容性未经验证。

4. Token 优化 vs 可读性：85% 的 token 节省是通过"操作参数化"实现的，但这也意味着单个工具的 schema 非常复杂，对于 MCP 客户端的 schema 解析能力有一定要求。

---

七、行业意义与增长趋势

coolify-mcp 代表了 AI 基础设施管理的一个新兴方向：AI-Native DevOps。传统 DevOps 工具（Terraform、Ansible 等）强调声明式配置，而 MCP 化的工具强调对话式交互，让 AI 能够在理解用户意图后自主执行复杂操作序列。

从增长数据看，456 stars 对于一个相对小众的垂直工具（MCP + Coolify 交叉领域）来说表现不俗。GitHub 维护了详细的 CHANGELOG（36KB），版本迭代速度快（当前 v2.12.0），作者积极响应 issue，社区活跃度较高。

随着 MCP 协议被更多 AI 厂商采用，这类"AI + 自托管基础设施"的工具可能会成为下一个增长热点——尤其是在数据隐私意识增强、企业倾向私有化部署的大背景下。