Coolify MCP Server For Claude Code

冷却MCP服务器

一种集成了以下功能的模型上下文协议（MCP）服务器 冷却 让人工智能助手通过一个干净的工具包来管理你的Coolify实例，该工具包包装了官方的REST API。

______________________________________________________________________

目录

• 特性

• 先决条件

• 安装

• 配置

- 环境设置 - Claude代码设置 - 光标设置

• API代币生成

• 可用工具

• 使用示例

• 发展

• api参考

• 故障排除

• 安全

• 贡献

• 许可证

• 支持

______________________________________________________________________

特性

核心能力

• 覆盖关键的Coolify API端点 （应用程序、服务、部署、团队、私钥、域、运行状况/版本）
• 团队管理 –列出团队，获取团队详细信息，查看成员
• 服务器和域洞察 –查询每台服务器配置的域
• 应用程序生命周期 –启动/停止/重新启动和创建应用程序
• 服务管理 –列出/创建/启动/停止/重新启动服务
• 部署 –列出正在运行的部署；按UUID获取部署
• 私钥 列出并创建用于服务器身份验证的SSH私钥
• 环境变量 –应用程序/服务环境变量的CRUD

注：某些聚合操作（例如“按服务器分配资源”）是通过客户端过滤支持的端点而不是通过专用的API路径来实现的。

______________________________________________________________________

先决条件

• Node.js v18或更新版本
• npm 或 纱线
• 跑步 冷却 实例（自托管或云）
• A. Coolify API代币 具有适当的权限

______________________________________________________________________

安装

1） 克隆并安装

git clone https://github.com/forsonny/Coolify-MCP-Server-for-Claude-Code.git
cd Coolify-MCP-Server-for-Claude-Code
npm install

2） 构建

npm run build

（将TypeScript编译为 dist/)

______________________________________________________________________

配置

环境设置

创建一个 .env 项目根目录下的文件：

# Required
COOLIFY_BASE_URL=https://your-coolify-instance.com
COOLIFY_API_TOKEN=your-api-token-here

# Optional
COOLIFY_TIMEOUT=30000

备注

• 使用 完整基本URL （没有尾随斜线）。例子： https://coolify.example.com
• 做 不 在中使用内联注释 .env 价值观。
• 永不承诺 .env 版本控制。

Claude代码设置

您可以将服务器连接到 克劳德代码 使用自动设置脚本或手动。

选项A——自动设置（推荐）

最简单的方法是使用安装脚本：

# Run the setup script
npm run setup

这将：

• 验证您的 .env 文件配置
• 如果需要，构建TypeScript项目
• 生成正确的 claude mcp add-json 带有环境变量的命令
• 提供故障排除提示

选项B——手动设置

如果您更喜欢手动设置，有两种方法：

方法1：使用显式环境变量（最可靠）

claude mcp add-json coolify '{
  "type": "stdio",
  "command": "node", 
  "args": ["/absolute/path/to/Coolify-MCP-Server-for-Claude-Code/dist/index.js"],
  "env": {
    "COOLIFY_BASE_URL": "https://your-coolify-instance.com",
    "COOLIFY_API_TOKEN": "your-api-token-here",
    "COOLIFY_TIMEOUT": "30000"
  }
}' -s local

方法2：简单命令（依赖.env文件）

claude mcp add coolify "node /absolute/path/to/Coolify-MCP-Server-for-Claude-Code/dist/index.js" -s local

验证连接

claude mcp list

选项C——从Claude Desktop导入 如果您已经在Claude Desktop中配置了服务器：

claude mcp add-from-claude-desktop
claude mcp list

重要提示： 方法1（显式环境变量）更可靠，因为它确保环境变量对MCP服务器进程可用，而不管Claude Code从哪个工作目录启动服务器。

提示：一些设置将Claude Code MCP配置存储在 ~/.claude.json。桌面应用程序使用 claude_desktop_config.json 在您的操作系统应用程序数据目录下。

光标设置

光标 支持MCP。最简单的路线是通过 设置→ 扩展→ MCP服务器→ 添加服务器，然后指向您构建的脚本(node …/dist/index.js)并添加三个环境变量。保存后重新启动Cursor。

有关高级/企业设置，请参阅Cursor关于程序化注册的MCP文档。

______________________________________________________________________

API代币生成

1. 打开您的Coolify仪表板。
2. 引导到 密钥和令牌→ API令牌.
3. 创建一个新令牌（命名为“MCP服务器”），选择所需的权限，并可选择设置过期时间。
4. 复制令牌 一次 当显示时，将其粘贴到您的 .env.

______________________________________________________________________

可用工具

系统

团队

服务器和域

应用程序

服务

部署和密钥

环境变量

应用程序和服务环境变量支持：列表、创建、更新（单次/批量）和删除。

______________________________________________________________________

使用示例

连接后，您可以尝试使用自然语言：

基础

"List my applications"
"Who's in the current team?"
"What version is my Coolify instance?"

服务器和应用程序

"Show domains for server 123e4567-e89b-12d3-a456-426614174000"
"Create a new app from https://github.com/user/repo"
"Restart the backend app"

服务与环境变量

"List running services"
"Create a PostgreSQL service on the main server"
"Add DATABASE_URL to the frontend app"

______________________________________________________________________

发展

开发模式（观看）：

npm run dev

构建：

npm run build

设置：

npm run setup

清洁：

npm run clean

项目结构

Coolify-MCP-Server-for-Claude-Code/
├── src/
│   ├── index.ts           # MCP server entrypoint
│   ├── coolify-client.ts  # Coolify API client
│   └── types.ts           # Type definitions
├── dist/                  # Compiled JS (generated)
├── .env                   # Environment variables (create this)
├── setup-mcp.js           # Setup script for easy configuration
├── package.json
├── tsconfig.json
└── README.md              # This file

______________________________________________________________________

api参考

此服务器使用的选定端点映射

端点路径遵循官方的Coolify API和 不要 使用一个 /api/v1 前缀。

环境变量标志

服务是预构建的映像（没有构建阶段），因此 is_build_time 对服务没有影响。

______________________________________________________________________

故障排除

服务器无法启动

• 确认节点≥18： node --version
• 重新安装deps： rm -rf node_modules && npm install
• 重建： npm run clean && npm run build
• 确认MCP配置中的绝对路径

身份验证错误 (401 Unauthorized)

• 验证令牌是否有效，以及其作用域是否适用于正确的团队
• 如果令牌已过期，则重新创建令牌；粘贴到 .env

连接问题(ECONNREFUSED/超时）

• 检查 COOLIFY_BASE_URL （无尾随斜线）
• 确保Coolify实例可访问且运行正常
• 增加 COOLIFY_TIMEOUT 对于慢速链接

工具未出现

• 重新启动客户端（克劳德代码/光标）
• 证实 claude mcp list
• 检查终端中的服务器日志
• 确保为MCP过程设置环境变量

环境变量问题

如果你看到 COOLIFY_BASE_URL and COOLIFY_API_TOKEN environment variables are required 错误：

1. 使用自动设置脚本：

   npm run setup

1. 或者使用显式环境变量：

删除现有的MCP服务器，并使用显式环境变量重新添加：

   claude mcp remove coolify -s local
   claude mcp add-json coolify '{
     "type": "stdio",
     "command": "node",
     "args": ["/absolute/path/to/your/dist/index.js"],
     "env": {
       "COOLIFY_BASE_URL": "https://your-coolify-instance.com",
       "COOLIFY_API_TOKEN": "your-api-token-here"
     }
   }' -s local

1. 验证.env文件是否存在并且具有正确的值：

   cat .env

为什么会发生这种情况： 当Claude Code启动MCP服务器时，它们可能会从不同的工作目录运行，导致 .env 找不到文件。MCP配置中的显式环境变量解决了这个问题。

调试模式

DEBUG=coolify-mcp npm run dev

______________________________________________________________________

安全

• 将API令牌排除在VCS之外；定期轮换
• 使用HTTPS；考虑私有实例的IP分配列表/VPN
• 添加 .env 向 .gitignore；限制文件权限
• 每个环境使用最少的特权令牌；定期审计和撤销

______________________________________________________________________

贡献

我们欢迎捐款！

1. 分叉 repo和克隆你的fork

   git clone https://github.com//Coolify-MCP-Server-for-Claude-Code.git

1. 创建分支

   git checkout -b feat/your-feature

1. 代码与测试 –遵循现有风格；在有用的地方添加测试

1. 提交

   git commit -m "feat: add "

1. 推送并打开PR

   git push origin feat/your-feature

指南

• TypeScript最佳实践；在可行的情况下向后兼容
• 清除提交消息和错误处理
• 添加功能时更新README

______________________________________________________________________

许可证

麻省理工学院——见 许可证.

______________________________________________________________________

支持

问题 –在GitHub上打开

文档

• Coolify API参考
• MCP SDK文档
• Claude代码文档
• 光标MCP指南

版本： 1.0.0 维护人员： @ 福索尼