AI导哈

Coolify MCP服务器

一个用于Coolify部署平台集成的4工具统一模型上下文协议（MCP）服务器，使AI助手能够与Coolify自托管实例交互，进行应用程序部署、管理和监控。

  • by GoCoder7
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 gocoder7/coolify-mcp-server

使用说明

冷却MCP服务器

A. 4-工具统一 模型上下文协议（MCP）服务器 冷却 部署平台集成。此服务器使AI助手能够与Coolify Self托管实例进行交互，以进行应用程序部署、管理和监控。

🎯 针对VS Code的128个工具限制进行了优化，减少了87%（19→4个工具）

特性

🚀 应用程序管理

  • 使用可选的强制部署和分支选择部署应用程序
  • 获取详细的应用程序信息和状态
  • 列出具有过滤功能的应用程序
  • 启动、停止和重新启动应用程序
  • 监控部署状态和运行状况
  • 创建新应用程序

🔧 环境和配置

  • 更新和检索环境变量
  • 配置域和SSL证书
  • 检索应用程序日志以进行调试
  • 管理敏感和构建时间变量

🖥️ 系统管理

  • 列出并监控服务器
  • 管理团队和权限
  • 查看已部署的服务（数据库、缓存等）
  • 测试API连接和系统运行状况

📚 内置文档

  • 搜索文档：查找相关的Coolify指南和参考资料
  • api参考：访问全面的API文档和示例
  • 故障排除指南：获取常见部署和配置问题的帮助
  • 特定主题帮助：获取特定功能的目标文档

非常适合没有Context7 MCP访问权限的AI代理-不需要外部文档依赖！

🧪 完整的测试套件

  • 100%测试成功率：综合集成测试
  • 演示环境：使用Docker Compose进行完整的Coolify设置
  • 浏览器自动化：MCP剧作家集成
  • 真正的API测试：直接Coolify实例验证

先决条件

  • Node.js 18+
  • 正在运行的Coolify Self托管实例
  • 使用适当权限冷却API令牌

安装

  1. 克隆或下载此存储库

    git clone <repository-url>
cd coolify-mcp-server

  2. 安装依赖项

    npm install

  3. 配置环境变量

    cp .env.example .env
# Edit .env with your Coolify instance details

  4. 构建项目

    npm run build

配置

环境变量

创建一个 .env 包含以下变量的文件：

# Required: Your Coolify instance URL
COOLIFY_BASE_URL=https://your-coolify-instance.com

# Required: API token from Coolify
COOLIFY_API_TOKEN=your-api-token-here

# Optional: Team ID for scoped access
COOLIFY_TEAM_ID=your-team-id

获取您的API代币

  1. 登录您的Coolify仪表板
  2. 首选 设置 → 密钥和令牌 → API令牌
  3. 点击 创建新令牌
  4. 选择权限：
    • read-only：仅查看数据
    • read:sensitive：查看敏感数据
    • *：完全访问（建议自动化）
  5. 将生成的令牌复制到您的 .env 文件

⚠️ 安全说明：API令牌仅显示一次。安全地存储它们，永远不要将其提交给版本控制。

用法

发展模式

npm run dev

生产模式

npm start

与AI助手集成

此MCP服务器提供 4个统一工具 对于AI助手，针对VS Code中的128个工具限制进行了优化：

📱 应用程序管理(coolify_application_management)

具有8个操作的统一工具：

  • deploy -部署具有可选强制部署和分支选择的应用程序
  • get -获取详细的应用程序信息
  • list -列出所有具有过滤功能的应用程序
  • status -获取部署状态和运行状况
  • start -启动应用程序
  • stop -停止应用程序
  • restart -重新启动应用程序
  • create -创建新应用程序

⚙️ 环境配置(coolify_environment_configuration)

环境和域管理的统一工具：

  • env_vars -更新和检索环境变量
  • domains -配置域和SSL证书
  • logs -检索应用程序日志以进行调试

🖥️ 系统管理(coolify_system_management)

服务器和基础设施的统一工具：

  • servers -列出并监控服务器
  • teams -管理团队和权限
  • services -查看已部署的服务（数据库、缓存等）
  • health_check -测试API连接和系统运行状况

📚 文件(coolify_documentation)

具有6个操作的统一文档工具：

  • search -搜索内置的Coolify文档
  • get -获取特定主题的文档
  • api_reference -获取带有示例的API参考文档
  • troubleshooting -获取常见问题的故障排除指南
  • topics -列出可用的文档主题
  • api -获取API端点文档

非常适合没有Context7 MCP访问权限的AI代理-不需要外部文档依赖！

示例用法

以下是您可以使用AI助手使用的一些示例命令 统一工具:

应用程序管理：

"Deploy my application with ID 'app-123' using force deployment"
"Get details for application 'my-web-app'"
"List all running applications"
"Check the status of application 'app-456'"
"Start application 'my-backend'"
"Restart application 'frontend-app'"

环境配置：

"Update environment variables for 'app-789': set DATABASE_URL and REDIS_URL"
"Get current environment variables for 'my-app'"
"Set the domain 'example.com' for application 'app-456' with HTTPS enabled"
"Get the logs for application 'my-web-app'"

系统管理：

"List all servers and their status"
"Get information about teams"
"Show all running services"
"Check system health and API connectivity"

文档：

"Search documentation for 'deployment failed'"
"Get troubleshooting help for SSL certificate issues"
"Show me API reference for environment variables"
"List all available documentation topics"
"Get API documentation for applications endpoint"

文档功能

MCP服务器包括通过统一的 coolify_documentation 工具：

// Search for deployment-related documentation
await callTool('coolify_documentation', { action: 'search', query: 'deployment failed' });

// Get API reference for applications endpoint
await callTool('coolify_documentation', { action: 'api_reference', endpoint: 'applications' });

// Get troubleshooting help for SSL issues
await callTool('coolify_documentation', { action: 'troubleshooting', issue: 'ssl certificate' });

// List all available topics
await callTool('coolify_documentation', { action: 'topics' });

// Get general documentation on environment variables
await callTool('coolify_documentation', { action: 'get', topic: 'environment variables' });

内置文档封面：

  • API参考及示例
  • 分步部署指南
  • 环境变量配置
  • 域和SSL设置
  • 常见故障排除场景

api参考

此MCP服务器与Coolify API交互。有关API的详细文档，请访问：

建筑

coolify-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server (unified version)
│   ├── types/
│   │   ├── coolify.ts        # Coolify API types
│   │   └── mcp.ts           # MCP tool schemas
│   ├── utils/
│   │   └── coolify-client.ts # Coolify API client
│   └── tools/
│       ├── application-unified.ts    # Unified application management
│       ├── environment-unified.ts    # Unified environment & domain tools
│       ├── system-unified.ts        # Unified system management
│       └── documentation-unified.ts  # Unified documentation tools
├── demo-server/
│   ├── docker-compose.yml    # Complete Coolify demo environment
│   └── DEMO-SETUP.md        # Demo setup instructions
├── .env.example             # Environment configuration template
├── test-*.js               # Comprehensive test suites
├── tsconfig.json           # TypeScript configuration
└── package.json           # Project dependencies

演示环境

该项目包括 完整的Coolify演示环境 用于测试：

cd demo-server
docker compose up -d

包括：

  • ✅ Coolify最新版本
  • ✅ PostgreSQL数据库
  • ✅ Redis缓存
  • ✅ Soketi WebSocket服务器
  • ✅ 预配置演示用户
  • ✅ Web界面位于http://localhost:8000

演示凭据：

  • 电子邮件： test@example.com
  • 密码： password123

发展

建筑

npm run build

类型检查

npm run type-check

测试文档功能

node test-docs.js

这将测试所有内置文档功能，而不需要Coolify连接。

使用演示环境进行测试

# Start the demo environment
cd demo-server && docker compose up -d

# Run comprehensive tests
npm test

测试套件：

  • test-integration.js -Docker环境和构建测试
  • test-mcp-simple.js -MCP服务器功能测试
  • test-web-interface.js -Playwright浏览器自动化测试
  • test-real-coolify.js -真正的Coolify集成测试

预期结果： 100%测试成功率

清洁

npm run clean

支持的Coolify版本

此MCP服务器设计用于：

  • Coolify v4.x（自托管）
  • API版本：v1

安全考虑

  • API令牌：使用环境变量安全地存储API令牌
  • 网络接入：确保您的Coolify实例可以从运行此MCP服务器的位置访问
  • 权限：根据您的用例使用适当的API令牌权限
  • 超文本传输安全协议：生产Coolify实例始终使用HTTPS

故障排除

常见问题

  1. 连接失败

    • 验证 COOLIFY_BASE_URL 正确且可访问
    • 检查API令牌是否具有正确的权限
    • 确保Coolify实例正在运行

  2. 权限不足

    • 验证API令牌是否具有足够的权限
    • 检查您的设置是否需要团队ID

  3. 未找到应用程序

    • 验证应用程序ID是否正确
    • 确保您有权访问该应用程序

调试模式

通过设置启用调试日志记录：

NODE_ENV=development npm run dev

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

更新日志

v1.0.0

  • ✅ 4统一工具：针对VS Code的128工具限制进行了优化
  • ✅ 完整演示环境：Docker使用工作的Coolify实例编写安装程序
  • ✅ 100%测试覆盖率：全面的测试套件，成功率100%
  • ✅ 内置文档：不需要外部依赖关系
  • ✅ 浏览器自动化：MCP Playwright集成测试
  • ✅ 应用程序管理：部署、管理和监视应用程序
  • ✅ 环境配置：管理环境变量、域和日志
  • ✅ 系统管理：服务器、团队和服务管理
  • ✅ 完全支持TypeScript：通过Zod验证实现完全类型安全

相关 MCP