AI导哈

Coolify部署管理服务器

一个将Coolify的REST API暴露为MCP工具的平台适配器，使AI助手能够通过模型上下文协议管理Coolify部署。

  • by penniger
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 okwn/Coolify-MCP

使用说明

冷却mcp

Coolify的MCP服务器 --使AI助手能够通过模型上下文协议管理Coolify部署。

目的

coolify-mcp 是一个平台适配器，将Coolify的REST API公开为MCP工具和资源。它使AI编码助手（Claude Code、OpenCode、Codex等）能够检查、创建、配置和监控Coolify上的部署，而无需用户导航Coolify仪表板。

为什么它存在

通过仪表板部署应用程序速度慢且容易出错。当AI助手能够以编程方式与Coolify交互时，他们可以：

  • 检查代码库并推荐部署策略（项目检测）
  • 生成一个 deploy.intent.yaml 清单
  • 自动创建具有正确设置的应用程序
  • 配置环境变量和机密
  • 触发部署和状态轮询
  • 读取日志以诊断故障

该MCP服务器弥补了人工智能助手的自然语言理解与Coolify的API驱动部署平台之间的差距。

主要特点

  • 15个MCP工具 覆盖整个应用程序生命周期
  • 项目检测 --分析本地代码以推荐部署策略
  • Zod模式验证 --所有工具输入均已验证，错误信息清晰
  • TypeScript优先 --全程全型安全
  • 读/写分离 --可安全探索的只读工具；变异工具需要确认

架构摘要

┌─────────────────┐     MCP       ┌──────────────────┐     REST API     ┌─────────────┐
│  AI Assistant   │◄──────────────►│    coolify-mcp    │◄─────────────────►│   Coolify   │
│                 │                │   (TypeScript)    │                   │   Server    │
└─────────────────┘                └──────────────────┘                   └─────────────┘

组件

组件 位置 目的
MCP服务器 src/server/ 协议处理程序、工具路由
工具 src/tools/ 15个工具实现
API客户端 src/adapters/coolify-api/ Typed Coolify API客户端
项目检测 src/detection/ 本地代码库分析
架构 src/schemas/ TypeScript类型+Zod验证

支持的工具

项目管理

工具 说明
list_projects 列出所有Coolify项目

应用程序管理

工具 说明
list_applications 列出具有筛选功能的应用程序
get_application 获取应用程序详细信息

应用程序创建

工具 说明
create_application_public_repo 从公共Git存储库创建
create_application_private_repo_deploy_key 带有部署密钥的私有仓库
create_application_private_repo_github_app 通过GitHub应用程序的私有仓库
create_application_dockerfile 使用自定义Dockerfile创建
create_application_docker_image 从预构建的容器映像创建
create_application_compose 创建Docker Compose应用程序

环境变量

工具 说明
list_envs 列出环境变量
set_env 设置单个环境变量
bulk_set_envs 设置多个环境变量

部署操作

工具 说明
trigger_deploy 触发新部署
get_logs 获取部署或应用程序日志
get_deployment_status 获取部署状态

项目检测

工具 说明
detect_project_type 分析代码库，推荐策略

项目结构

coolify-mcp/
├── src/
│   ├── server/                  # MCP server implementation
│   ├── tools/                    # MCP tool definitions (15 tools)
│   ├── adapters/coolify-api/     # Coolify API client
│   ├── detection/                # Project type detection logic
│   ├── schemas/                 # TypeScript + Zod schemas
│   └── prompts/                 # Prompt templates
├── docs/
│   ├── coolify-api-mapping.md   # Tool → API endpoint mapping
│   └── detection-rules.md        # Project detection heuristics
├── examples/                     # JSON example payloads
├── tests/                       # Unit and integration tests
├── package.json
└── README.md

安装

先决条件

  • Node.js 18+
  • 正在运行的Coolify实例（建议使用v4.x）
  • Coolify API密钥

从源代码构建

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

配置

环境变量

export COOLIFY_URL="http://your-coolify-instance:3000"
export COOLIFY_API_KEY="your-api-key"

Claude代码设置

添加到 ~/.claude/settings.json:

{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["./path/to/coolify-mcp/dist/server.js"],
      "env": {
        "COOLIFY_URL": "http://your-coolify-instance:3000",
        "COOLIFY_API_KEY": "your-api-key"
      }
    }
  }
}

例子

部署Node.js应用程序

import { createServer } from 'coolify-mcp'

const server = await createServer()

// List projects
const projects = await server.handleToolCall('list_projects', {})

// Create application
const app = await server.handleToolCall('create_application_public_repo', {
  projectId: 'proj_xxxxxxxx',
  name: 'my-node-app',
  repository: 'owner/my-node-app',
  branch: 'main',
  buildStrategy: 'nixpacks',
  port: 3000
})

// Set environment variables
await server.handleToolCall('bulk_set_envs', {
  applicationId: app.application.id,
  envVars: [
    { key: 'NODE_ENV', value: 'production' },
    { key: 'DATABASE_URL', value: '${DATABASE_URL}', isSecret: true }
  ]
})

// Trigger deployment
const deployment = await server.handleToolCall('trigger_deploy', {
  applicationId: app.application.id
})

检测项目类型

const detection = await server.handleToolCall('detect_project_type', {
  projectPath: '/path/to/my-project'
})

console.log('Detected:', detection.kind)
console.log('Confidence:', detection.confidence)
console.log('Reasons:', detection.reasons)

有效载荷示例

与实际API模式匹配的JSON示例文件位于 examples/:

文件 描述
examples/create-source-app.json create_application_public_repo 有效载荷
examples/create-compose-app.json create_application_compose 有效载荷
examples/set-env-vars.json bulk_set_envs 有效载荷
examples/trigger-deploy.json trigger_deploy 有效载荷
examples/get-application.json get_application 有效载荷
examples/get-logs.json get_logs 有效载荷

所有示例文件都经过清理 --没有真正的凭据或端点引用。使用前替换所有占位符ID。

测试夹具

用于测试检测和验证的真实项目夹具：

文件 描述
fixtures/valid-manifest.yaml 完整有效 deploy.intent.yaml
fixtures/invalid-manifest.yaml 故意错误清单（用于验证测试）
fixtures/package.json 使用Express+TypeScript的Node.js包.json
fixtures/Dockerfile 多阶段生产Dockerfile
fixtures/docker-compose.yml 多服务组合（web、api、worker、db、redis）
fixtures/monorepo-package.json 带有pnpm工作区的Monrepo根目录

安全和部署风险

风险 缓解
意外生产部署 突变前需要人类批准
日志中的秘密暴露 从未记录API密钥；使用 isSecret: true 对于敏感的环境变量
速率限制 冷却API，限制在约100 req/min；在高容量工作流中实施回退
端口冲突 检测逻辑警告常见的配置错误
资源耗尽 设置 memoryLimit 和 cpuLimit 在 deploy.intent.yaml

文件准确性说明

官方的 冷却文档 仍然是所有平台行为、API端点、身份验证详细信息和配置选项的真相来源。

此存储库提供 平台适配器 -它将Coolify的REST API包装为MCP工具，供人工智能助手使用。这 docs/coolify-api-mapping.md 文件记录了此适配器调用哪些端点以及如何调用。它并不取代官方的Coolify API参考。

局限性

  • 不支持Coolify的一键式数据库部署
  • 不支持自动回滚配置
  • 不支持Coolify的“远程构建”功能
  • 实时部署事件没有webhook订阅
  • 单个Coolify实例（不支持多实例）
  • 需要具有完整项目/应用程序权限的API密钥

路线图

  • []添加回滚工具
  • []添加度量端点
  • []添加清理工具
  • []添加数据库管理工具
  • []支持Coolify的一键式数据库
  • []多实例支持

相关存储库

许可证

MIT许可证——见 许可证 文件以获取详细信息。

相关 MCP