Позволяет AI-клиенту развертывать, диагностировать и управлять приложениями, сервисами и базами данных на инстансах Coolify.
Также известен как clezcoding/awesome-coolify, awesome-coolify-mcp
- Звёзды
- 0
- Инструменты
- 45
- Загрузки, 30 дней
- —
- Последняя версия
- 0.1.2
- Последний коммит
- 14 нояб. 2026 г.
- Лицензия
- MIT
Что такое Coolify MCP?
Coolify — это MCP server. Позволяет AI-клиенту развертывать, диагностировать и управлять приложениями, сервисами и базами данных на инстансах Coolify. Он предоставляет 45 инструментов, например health, version, verify.
Сводка сгенерирована из README проекта
О Coolify MCP server
С awesome-coolify-mcp управление self-hosted инфраструктурой через AI-агентов становится реальностью. Этот MCP server позволяет разработчикам развертывать, диагностировать и управлять приложениями, сервисами и базами данных на инстансах Coolify напрямую из таких клиентов, как Cursor, Claude, VS Code или Windsurf. Он выступает в роли моста к Coolify REST API 4.1.x, предоставляя единый интерфейс для взаимодействия с вашим парком серверов.
Вместо использования множества разрозненных инструментов, сервер предоставляет 19 инструментов на базе действий (actions), которые используют единую структуру команд с полем action. Пользователи могут выполнять такие задачи, как отслеживание развертывания, просмотр логов или выполнение экстренных операций. Для настройки необходимо передать COOLIFY_URL и COOLIFY_TOKEN через переменные окружения в конфигурации вашего MCP клиента или зарегистрировать несколько инстансов в локальном JSON файле.
Безопасность встроена в рабочий процесс благодаря автоматическому маскированию секретов, таких как пароли и токены. Деструктивные действия требуют явного флага подтверждения, чтобы предотвратить случайные изменения. Сервер также обрабатывает временные сетевые сбои с помощью автоматических повторных попыток и предоставляет структурированные коды ошибок, помогая AI-агенту корректно обрабатывать сбои.
Что вы можете с ним делать
- 1Развертывание и мониторинг приложенийAI-агент может инициировать новое развертывание и отслеживать процесс сборки в режиме реального времени.
- 2Устранение неполадок инфраструктурыВы можете попросить агента просканировать весь ваш парк серверов, чтобы выяснить причину сбоя.
- 3Управление нагрузками баз данных и сервисовАгент может создавать и управлять различными рабочими нагрузками, включая базы данных и сервисы.
- 4Выполнение экстренных операцийРазработчик может дать агенту команду на выполнение критически важных задач, таких как остановка всех запущенных процессов.
Взято из README проекта. Каждый вариант использования проверен на соответствие цитате из него.
Как установить Coolify MCP
Форматы проверены 10 ноя 2026Добавить в CursorДобавить в GooseУстановка Coolify MCP в Claude Code
$ claude mcp add awesome-coolify -- npx -y awesome-coolify-mcpУстановка Coolify MCP в Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"awesome-coolify": {
"command": "npx",
"args": [
"-y",
"awesome-coolify-mcp"
]
}
}
}Установка Coolify MCP в VS Code
.vscode/mcp.json
{
"servers": {
"awesome-coolify": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"awesome-coolify-mcp"
]
}
}
}Установка Coolify MCP в VS Code CLI
$ code --add-mcp '{"name":"awesome-coolify","type":"stdio","command":"npx","args":["-y","awesome-coolify-mcp"]}'Установка Coolify MCP в Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"awesome-coolify": {
"command": "npx",
"args": [
"-y",
"awesome-coolify-mcp"
]
}
}
}Установка Coolify MCP в Codex
$ codex mcp add awesome-coolify -- npx -y awesome-coolify-mcpУстановка Coolify MCP в Codex config.toml
~/.codex/config.toml
[mcp_servers.awesome-coolify] command = "npx" args = ["-y", "awesome-coolify-mcp"]
Установка Coolify MCP в Gemini CLI
$ gemini mcp add -s user awesome-coolify npx -- -y awesome-coolify-mcpУстановка Coolify MCP в Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"awesome-coolify": {
"command": "npx",
"args": [
"-y",
"awesome-coolify-mcp"
]
}
}
}Инструменты Coolify MCP 45
Определено из READMEhealthversionverifyinfrastructure_overviewlistfindappserverscanlogsanalyzeget
| health | — | |
| version | — | |
| verify | — | |
| infrastructure_overview | — | |
| list | — | |
| find | — | |
| app | — | |
| server | — | |
| scan | — | |
| logs | — | |
| analyze | — | |
| get | — |
Показать все 45 инструментовПоказать меньше инструментов
deploywatchcancelpreflightrollbackservicedatabasecreate-git-appcreate-app-dbcreate-one-clickrecommendapplicationvalidatecreatesearchstop_allredeploy_projectrestart_projectaddupdatedeleteset-defaultimport-envcloud-infoupsertsetremoveclearsyncdiffauditwireresume
| deploy | — | |
| watch | — | |
| cancel | — | |
| preflight | — | |
| rollback | — | |
| service | — | |
| database | — | |
| create-git-app | — | |
| create-app-db | — | |
| create-one-click | — | |
| recommend | — | |
| application | — | |
| validate | — | |
| create | — | |
| search | — | |
| stop_all | — | |
| redeploy_project | — | |
| restart_project | — | |
| add | — | |
| update | — | |
| delete | — | |
| set-default | — | |
| import-env | — | |
| cloud-info | — | |
| upsert | — | |
| set | — | |
| remove | — | |
| clear | — | |
| sync | — | |
| diff | — | |
| audit | — | |
| wire | — | |
| resume | — |
Конфигурация
COOLIFY_MCP_LOGCOOLIFY_TOKENCOOLIFY_URLCOOLIFY_VERIFY_SSL
| Название | Описание | Тип |
|---|---|---|
| COOLIFY_MCP_LOG | — | |
| COOLIFY_TOKEN | — | |
| COOLIFY_URL | — | |
| COOLIFY_VERIFY_SSL | — |
Автоматические проверки
Запущено 13 нояб. 2026 г.Полный отчёт →Прошло наши автоматизированные проверки. Это не аудит безопасности: изучите код и предоставьте серверу минимально необходимый доступ. Как работают проверки
- Связанный и доступный исходный репозиторийПройдено
- Open source лицензия (OSI)Пройдено
- Коммит или релиз за последний годПройдено
- Имя пакета не похоже на популярный пакетПройдено
- Удаленная конечная точка использует HTTPSНе проверялось
- Деструктивные инструменты помеченыНе проверялось
- Нет скрытых инструкций для моделиПройдено
- Нет критических предупреждений в пакете или его зависимостяхПройдено
README
Открыть на GitHub📋 Table of contents
- Overview
- Why awesome-coolify-mcp
- Features
- How it works
- Quick start
- Install
- Coolify Cloud
- Supported clients
- Environment variables
- MCP Prompts
- Tools reference
- Safety model
- Structured errors & retries
- Example agent workflows
- Status today
- Coming soon
- Local development
- Links
🔭 Overview
Self-hosted Coolify is one of the best open-source alternatives to Heroku/Vercel-style PaaS platforms — but wiring it up to an AI coding agent has historically meant piecing together several small, overlapping community MCP integrations, each with its own schema, its own error format, and its own idea of what "safe" looks like.
awesome-coolify-mcp 1.1.4 replaces that patchwork with a single, community-maintained MCP server that speaks Coolify's REST API 4.1.x through a clean, action-based tool surface. Source, docs, and npm distribution live in one public repo — clezcoding/awesome-coolify — while the installable package stays awesome-coolify-mcp. Instead of memorizing dozens of near-identical tool names, your agent calls one of 19 tools with an action field:
application({ action: "deploy", uuid: "<app-uuid>", wait: false })
deployment({ action: "watch", deployment_uuid: "<deployment_uuid>", timeout: 300 })
diagnose({ action: "scan" })
emergency({ action: "stop_all", confirm: true })
Under the hood, every call goes through the same request pipeline: Zod-validated input, retrying HTTP client, secret-aware output masking, and structured error envelopes with recovery hints — so your agent fails gracefully instead of guessing.
[!NOTE] This is a community project built for people who run their own Coolify instances. It is not affiliated with or endorsed by Coolify Labs.
🆚 Why awesome-coolify-mcp
| Typical setup without it | With awesome-coolify-mcp |
|---|---|
| Several overlapping community MCP tools, each with its own schema | One server, one consistent schema |
| Dozens of granular, single-purpose tools per resource | 19 tools with consistent action discriminators |
| Ad-hoc error strings that agents have to guess at | Structured codes (COOLIFY_401, COOLIFY_404, …) + machine-readable recovery hints |
| Secrets can leak straight into agent context | Default secret masking + confirmation gates on destructive actions |
| Read a wall of raw JSON to find what changed | Bounded, paginated projections tuned for LLM context windows |
Today, the shipped surface covers day-2 operations and infrastructure creation: verify connectivity, discover fleets, deploy and watch builds, inspect bounded logs, diagnose incidents, run gated emergency ops, and manage applications, services, databases, SSH keys, servers, projects, environments, backups, and environment variables.
✨ Features
- 19 action-based tools — call
application({ action: "deploy", uuid })instead of hunting through dozens of granular tool names. The registered surface issystem,meta,resource,diagnose,application,emergency,deployment,service,database,private_key,instance,manifest,server,project,environment,docs,recipe,setup, andintelligence. - Multi-instance registry & routing — register every Coolify instance you own in
~/.coolify-mcp/instances.jsonvia theinstancetool; per-call credential resolution with no cross-instance leakage. - Coolify Cloud aware —
instance({ action: "cloud-info" })for local discovery, team-scoped tokens, and structured cloud error codes (COOLIFY_CLOUD_FORBIDDEN,COOLIFY_CLOUD_UNSUPPORTED). - Local manifest cache —
.coolify/manifest.jsonsync viamanifest({ action: "sync" }), best-effort auto-hooks on app/service/DB mutations, and_meta.manifestWarningwhen the cache is stale. - Server branding — MCP list icon via
serverInfo.icons(embedded data URI + jsDelivr CDN entries fromdocs/assets/). - Ops workflows that mirror real incidents — a single
system.infrastructure_overviewcall for the big picture, fuzzyresource.findwhen you only remember a name or domain,diagnose.app/diagnose.serverfor a specific suspect, anddiagnose.scanwhen you just know something is wrong fleet-wide. - Deploy lifecycle agents can drive — start/stop/restart, force rebuild,
deployment.watchwith bounded backoff,deployment.logsfor builds, boundedapplication.logs, and runtime follow with idle/overall timeouts. - Full workload CRUD — create, inspect, update, delete, and operate applications, services, and databases; discover live one-click IDs with
service.list-types. - Recipes and guided setup — create git apps, app-plus-database stacks, and one-click services; run
setup.preflight,setup.wire, orsetup.resume; install four matching IDE workflow skills. - Safety by default, not by convention — emergency mutations require an explicit
confirm: true; sensitive keys (password,token,secret,private,env) render as***unless you opt in withreveal: true. - Agent-friendly failure modes — every error is a parseable envelope with a
code, a humanmessage, andrecoveryHints; transient network/429/5xx failures retry automatically with exponential backoff. - Broad client coverage out of the box — Cursor, VS Code / GitHub Copilot, Claude Desktop, Claude Code, Windsurf, and 15+ more via the install configurator.
🏗️ How it works
MCP client (Cursor / Claude / VS Code / …)
│ stdio MCP
▼
awesome-coolify-mcp (19 tools + action discriminator)
│ optional ~/.coolify-mcp/instances.json resolution
│ HTTPS + Bearer token
▼
Coolify REST API 4.1.x (servers · projects · applications · services · databases)
The server itself is intentionally boring: it holds no long-lived state and never touches your IDE's config files. Your MCP host (Cursor, Claude, VS Code, …) injects COOLIFY_URL and COOLIFY_TOKEN through its MCP config's env block — or you register named instances in ~/.coolify-mcp/instances.json via the instance tool. The process reads credentials from its environment (or the registry) and forwards authenticated requests to your Coolify instance over HTTPS.
🚀 Quick start
Prerequisites
- Node.js 24+ (Active LTS; CI uses Node 24)
- A self-hosted Coolify instance on 4.1.x
- An API token from Coolify → Keys & Tokens (authorization docs)
Run it directly with npx — no global install needed:
npx -y awesome-coolify-mcp
Wire the two required environment variables into your MCP host (see Install for every client). Once connected, a minimal smoke test looks like this:
meta({ action: "version" }) // server identity — no Coolify call
system({ action: "verify" }) // authenticate + connectivity check
system({ action: "infrastructure_overview" }) // servers, projects, apps, services, DBs at a glance
[!NOTE] Multi-instance users: register each Coolify instance first with
instance({ action: "add", name, url, token }), then callsystem({ action: "verify" }). Single-instance setups can skip the registry and useCOOLIFY_URL/COOLIFY_TOKENin MCP env.
[!IMPORTANT] Emergency actions (
stop_all,redeploy_project,restart_project) requireconfirm: true. Call them withoutconfirmfirst — you'll get awould_affectpreview and no mutation runs. Only passreveal: truewhen you genuinely need plaintext secrets back.
📦 Install
There are three equally supported paths — pick whichever fits your workflow.
1. One-click deeplink
Best when you already have your Coolify URL and token handy. Placeholder credentials work fine too — you'll be prompted to fill them in, or you can swap them afterwards.
Both editors implement a protocol handler that reads a JSON server configuration straight out of the URL:
| Client | Scheme | Encoding |
|---|---|---|
| Cursor | cursor://anysphere.cursor-deeplink/mcp/install?name=…&config=… (mirrored at https://cursor.com/en/install-mcp?… for a friendlier landing page) |
config is base64-encoded JSON |
| VS Code / Copilot | vscode:mcp/install?name=…&config=… |
config is URL-encoded JSON |
Clicking the button opens your editor, shows the server it's about to add, and lets you review or edit the command/env before accepting — nothing is installed silently.
2. Install configurator (GitHub Pages)
Use the browser configurator to type in your real COOLIFY_URL / COOLIFY_TOKEN and generate a ready-to-paste snippet for your exact client — JSON, TOML, or YAML depending on what that client expects.
Everything runs client-side in your browser. Your token is never sent to a backend, logged, or stored anywhere but the config file you paste it into.
3. Manual MCP config
Paste this into your host's MCP configuration file. Cursor example (~/.cursor/mcp.json for global, or .cursor/mcp.json in a project):
{
"mcpServers": {
"awesome-coolify-mcp": {
"command": "npx",
"args": ["-y", "awesome-coolify-mcp"],
"env": {
"COOLIFY_URL": "https://coolify.example.com",
"COOLIFY_TOKEN": "YOUR_COOLIFY_API_TOKEN",
"COOLIFY_VERIFY_SSL": "true",
"COOLIFY_MCP_LOG": "info"
}
}
}
}
A ready-made copy-paste template also lives at docs/mcp.example.json.
[!TIP] Using Coolify Cloud? Generate a team-scoped token and follow the registry setup in docs/en/cloud.md.
IDE skills (Cursor, Claude Code, Codex)
Install Coolify workflow skills for Cursor, Claude Code, and Codex:
npx skills add clezcoding/awesome-coolify -a cursor -a claude-code -a codex
After MCP install, run setup({ action: "preflight" }) or see the Setup guide for gh preflight, project linkage, and greenfield provisioning.
🖥️ Supported clients
| Client | Config location | Notes |
|---|---|---|
| Cursor | ~/.cursor/mcp.json |
One-click deeplink or manual JSON |
| VS Code / GitHub Copilot | .vscode/mcp.json |
Native inputs prompts for URL/token — no plaintext in the file |
| Claude Desktop | claude_desktop_config.json |
Manual JSON or configurator output today |
| Claude Code | ~/.claude.json or .mcp.json |
stdio via npx -y awesome-coolify-mcp |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
Same npx + env pattern as Cursor |
The install configurator covers a much wider matrix — OpenCode, Codex CLI, Gemini CLI, Cline, Kilo Code, Goose, LM Studio, Hermes Agent, Kimi Code, Google Antigravity, OpenClaw, and more — with the correct config shape for each.
[!NOTE] Claude Desktop currently uses manual JSON or configurator output.
🔐 Environment variables
| Variable | Required | Default | Description |
|---|---|---|---|
COOLIFY_URL |
yes* | — | Coolify base URL, no trailing slash — e.g. https://coolify.example.com |
COOLIFY_TOKEN |
yes* | — | Bearer API token, scoped to your team |
COOLIFY_VERIFY_SSL |
no | true |
Set to false only for self-signed certs on local/dev instances |
COOLIFY_MCP_LOG |
no | info |
Log verbosity: debug · info · error |
Credentials are read from the process environment (your IDE's MCP env block) or an optional local .env file when running the CLI directly. They are never echoed back inside tool responses.
[!NOTE] With the multi-instance registry (
~/.coolify-mcp/instances.json),COOLIFY_URLandCOOLIFY_TOKENbecome optional — theinstancetool resolves credentials per call. Env vars remain the simplest path for single-instance setups.
☁️ Coolify Cloud
awesome-coolify-mcp works with Coolify Cloud using the same 19 tools — team-scoped tokens, structured cloud error codes (COOLIFY_CLOUD_FORBIDDEN, COOLIFY_CLOUD_UNSUPPORTED), and local instance action cloud-info for discovery.
Run instance({ action: "cloud-info" }) before your first Cloud session — it returns isCloud, resolved url, credential source (registry | env | infer), knownLimits, and a docs link. No live API call.
Full setup, smoke test, and known limits → docs/en/cloud.md
💬 MCP Prompts
Six parameterized workflow prompts return numbered step guidance (English bodies) that orchestrate existing tools. Most arguments are optional — open any prompt without prefill.
| Prompt | Args (all optional unless noted) | Purpose |
|---|---|---|
deploy |
instance?, uuid?, force? |
Deploy an application and monitor until terminal status |
diagnose |
instance?, uuid? |
Investigate app, server, or fleet-wide issues (includes diagnose.analyze) |
new-project |
instance?, name?, server_uuid? |
Create project, environment, and optional server linkage |
incident |
instance?, uuid?, project_uuid? |
Triage with diagnose.analyze, logs, restart, or emergency redeploy |
rollback |
instance?, uuid?, name? |
Preview then confirm-gated deployment.rollback (STOP for human approval) |
maintenance-window |
instance?, uuid?, resource_type |
Guided change window using existing confirm-gated mutations |
Prompt handlers never read .coolify/manifest.json from disk — they steer the agent to resolve UUIDs from manifest or ask the user. Playbooks never auto-set confirm: true.
🧰 Tools reference
Every domain is exposed as one MCP tool with an action discriminator, so your agent's tool list stays short while the capability surface stays wide.
system({ action: "health" })
application({ action: "deploy", uuid: "<app-uuid>", wait: false })
deployment({ action: "watch", deployment_uuid: "<deployment_uuid>", timeout: 300 })
emergency({ action: "stop_all", confirm: true })
🖥️ system — connectivity & overview
Your first call in any session: is Coolify reachable, and what does the fleet look like right now?
| Action | Purpose |
|---|---|
health |
Verify Coolify API reachability |
version |
Coolify instance version string |
verify |
Authenticate; returns connectivity + version in one call |
infrastructure_overview |
Aggregate counts across servers, projects, applications, services, databases |
🏷️ meta — server identity
| Action | Purpose |
|---|---|
version |
awesome-coolify-mcp's own package name + semver — no Coolify call at all |
🔎 resource — discovery
For when you know roughly what you're looking for but not its exact UUID.
| Action | Purpose |
|---|---|
list |
Applications, services, and databases as summary projections, with pagination _meta |
find |
Fuzzy search by name, domain, or IP across servers and resources — ranked, capped at 10 |
🩺 diagnose — investigation
The tool you reach for when something feels wrong but you don't yet know what.
| Action | Purpose |
|---|---|
app |
App status, health, env var count, and recent deployments |
server |
Server resources, domains, and reachability |
scan |
Fleet-wide issues grouped by severity — the "what's on fire" button |
logs |
Resolve an application, return triage context, and optionally include bounded runtime or deployment logs |
analyze |
Log Brain — rule-based pattern triage on runtime (and optional build) logs; advisory-only (crash_loop, OOM, etc.) |
Вопросы о Coolify MCP
Как добавить Coolify MCP в Claude Code?
Выполните claude mcp add awesome-coolify -- npx -y awesome-coolify-mcp в терминале. Добавьте --scope user, чтобы сервер был доступен во всех проектах.
Как добавить Coolify MCP в Cursor?
Откройте ~/.cursor/mcp.json и добавьте сервер в mcpServers, используя конфигурацию Cursor из раздела установки выше.
Какие инструменты предоставляет Coolify MCP?
Он предоставляет 45 инструментов, включая health, version, verify, infrastructure_overview, list.
Что я могу делать с этим MCP server?
Вы можете проверять подключение, изучать инфраструктуру, создавать рабочие нагрузки, развертывать приложения, отслеживать логи, диагностировать инциденты и выполнять экстренные операции на инстансах Coolify.
Безопасно ли использовать его с конфиденциальными данными?
Да, сервер по умолчанию маскирует пароли и токены, а для выполнения деструктивных экстренных действий требуется явное подтверждение.