内容
# coolify-mcp
**适用于 Coolify 的 MCP 服务器** — 通过模型上下文协议使 AI 助手能够管理 Coolify 部署。
## 目的
`coolify-mcp` 是一个平台适配器，它将 Coolify 的 REST API 公开为 MCP 工具和资源。它使 AI 编程助手（Claude Code、OpenCode、Codex 等）能够在无需用户导航 Coolify 仪表盘的情况下，检查、创建、配置和监控 Coolify 上的部署。
## 为什么存在
通过仪表盘部署应用程序速度慢且容易出错。当 AI 助手可以与 Coolify 进行编程交互时，它们可以：
- 检查代码库并推荐部署策略（项目检测）
- 生成 `deploy.intent.yaml` 清单
- 自动创建具有正确设置的应用程序
- 配置环境变量和密钥
- 触发部署并轮询状态
- 读取日志来诊断故障
该 MCP 服务器弥合了 AI 助手自然语言理解与 Coolify API 驱动的部署平台之间的差距。
## 关键功能
- **15 个 MCP 工具**，涵盖整个应用程序生命周期
- **项目检测** — 分析本地代码以推荐部署策略
- **Zod 模式验证** — 所有工具输入均已验证，错误消息清晰
- **TypeScript-first** — 整个过程完全类型安全
- **读写分离** — 只读工具对于探索是安全的；变更工具需要确认
## 架构摘要
```
┌─────────────────┐ MCP ┌──────────────────┐ REST API ┌─────────────┐
│ AI 助手 │◄──────────────►│ coolify-mcp │◄─────────────────►│ Coolify │
│ │ │ （TypeScript） │ │ 服务器 │
└─────────────────┘ └──────────────────┘ └─────────────┘
```
### 组件
| 组件 | 位置 | 目的 |
|----------|----------|---------|
| MCP 服务器 | `src/server/` | 协议处理程序，工具路由 |
| 工具 | `src/tools/` | 15 个工具实现 |
| API 客户端 | `src/adapters/coolify-api/` | 类型化的 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 服务器实现
│ ├── tools/ # MCP 工具定义（15 个工具）
│ ├── adapters/coolify-api/ # Coolify API 客户端
│ ├── detection/ # 项目类型检测逻辑
│ ├── schemas/ # TypeScript + Zod 模式
│ └── prompts/ # 提示模板
├── docs/
│ ├── coolify-api-mapping.md # 工具 → API 端点映射
│ └── detection-rules.md # 项目检测启发式
├── examples/ # JSON 示例负载
├── tests/ # 单元测试和集成测试
├── package.json
└── README.md
```
## 安装
### 先决条件
- Node.js 18+
- 运行中的 Coolify 实例（推荐 v4.x）
- Coolify API 密钥
### 从源代码构建
```bash
git clone https://github.com/REPLACE_WITH_ORG/coolify-mcp
cd coolify-mcp
npm install
npm run build
```
## 配置
### 环境变量
```bash
export COOLIFY_URL="http://your-coolify-instance:3000"
export COOLIFY_API_KEY="your-api-key"
```
### Claude Code 设置
添加到 `~/.claude/settings.json`：
```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 应用程序
```typescript
import { createServer } from 'coolify-mcp'
const server = await createServer()
// 列出项目
const projects = await server.handleToolCalls('list_projects', {})
// 创建应用程序
const app = await server.handleToolCalls('create_application_public_repo', {
projectId: 'proj_xxxxxxxx',
name: 'my-node-app',
repository: 'owner/my-node-app',
branch: 'main',
buildStrategy: 'nixpacks',
port: 3000
})
// 设置环境变量
await server.handleToolCalls('bulk_set_envs', {
applicationId: app.application.id,
envVars: [
{ key: 'NODE_ENV', value: 'production' },
{ key: 'DATABASE_URL', value: '${DATABASE_URL}', isSecret: true }
]
})
// 触发部署
const deployment = await server.handleToolCalls('trigger_deploy', {
applicationId: app.application.id
})
```
### 检测项目类型
```typescript
const detection = await server.handleToolCalls('detect_project_type', {
projectPath: '/path/to/my-project'
})
console.log('Detected:', detection.kind)
console.log('Confidence:', detection.confidence)
console.log('Reasons:', detection.reasons)
```
### 示例负载
`examples/` 目录中的 JSON 示例文件与实际 API 模式匹配：
| 文件 | 描述 |
|------|-------------|
| `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
用于测试检测和验证的现实项目fixtures：
| 文件 | 描述 |
|------|-------------|
| `fixtures/valid-manifest.yaml` | 完整的有效 `deploy.intent.yaml` |
| `fixtures/invalid-manifest.yaml` | 具有故意错误的清单（用于验证测试） |
| `fixtures/package.json` | 具有 Express + TypeScript 的 Node.js package.json |
| `fixtures/Dockerfile` | 多阶段生产 Dockerfile |
| `fixtures/docker-compose.yml` | 多服务组合（web、api、worker、db、redis） |
| `fixtures/monorepo-package.json` | 具有 pnpm 工作区的 monorepo 根目录 |
## 安全性和部署风险
| 风险 | 缓解措施 |
|------|------------|
| 意外生产部署 | 在变更前需要人工审批 |
| 日志中暴露密钥 | API 密钥从不记录；对敏感环境变量使用 `isSecret: true` |
| 速率限制 | Coolify API 限制在 ~100 req/min；在大批量工作流中实施回退 |
| 端口冲突 | 检测逻辑警告常见错误配置 |
| 资源耗尽 | 在 `deploy.intent.yaml` 中设置 `memoryLimit` 和 `cpuLimit` |
## 文档准确性说明
官方 [Coolify 文档](https://coolify.io/docs) 仍然是所有平台行为、API 端点、身份验证详细信息和配置选项的真实来源。
该存储库提供了一个**平台适配器** — 它将 Coolify 的 REST API 封装为 MCP 工具，供 AI 助手使用。`docs/coolify-api-mapping.md` 文件记录了此适配器调用哪些端点以及如何调用。 它不能替代官方的 Coolify API 参考。
## 限制
- 不支持 Coolify 的一键式数据库部署
- 不支持自动回滚配置
- 不支持 Coolify 的“远程构建”功能
- 没有用于实时部署事件的 webhook 订阅
- 单个 Coolify 实例（不支持多实例）
- 需要具有完全项目/应用程序权限的 API 密钥
## 路线图
- [ ] 添加回滚工具
- [ ] 添加指标端点
- [ ] 添加清理工具
- [ ] 添加数据库管理工具
- [ ] 支持 Coolify 的一键式数据库
- [ ] 多实例支持
## 相关存储库
<!-- 发布前更新这些 URL。将 REPLACE_WITH_ORG 替换为您的 GitHub 组织。-->
- [dokploy-mcp](https://github.com/REPLACE_WITH_ORG/dokploy-mcp) — Dokploy 的 MCP 服务器
- [claude-skill-autodeploy](https://github.com/REPLACE_WITH_ORG/claude-skill-autodeploy) — Claude Code 部署技能
- [opencode-skill-autodeploy](https://github.com/REPLACE_WITH_ORG/opencode-skill-autodeploy) — OpenCode 部署技能
- [codex-skill-autodeploy](https://github.com/REPLACE_WITH_ORG/codex-skill-autodeploy) — Codex 部署技能
## 许可证
MIT 许可证 — 参见 [LICENSE](LICENSE) 文件获取详细信息。
