Permet à un client IA de déployer, diagnostiquer et gérer des applications, des services et des bases de données sur des instances Coolify.
Aussi connu sous clezcoding/awesome-coolify, awesome-coolify-mcp
- Étoiles
- 0
- Outils
- 45
- Téléchargements, 30 jours
- —
- Dernière version
- 0.1.2
- Dernier commit
- 14 nov. 2026
- Licence
- MIT
Qu'est-ce que Coolify MCP ?
Coolify est un serveur MCP. Permet à un client IA de déployer, diagnostiquer et gérer des applications, des services et des bases de données sur des instances Coolify. Il expose 45 outils, comme health, version, verify.
Résumé généré à partir du README du projet
À propos du MCP server Coolify
La gestion d'une infrastructure auto-hébergée via un agent de codage IA est possible avec awesome-coolify-mcp. Ce serveur permet aux développeurs de déployer, diagnostiquer et gérer des applications, des services et des bases de données sur des instances Coolify directement depuis des clients comme Cursor, Claude, VS Code ou Windsurf. Il agit comme une passerelle vers l'API REST 4.1.x de Coolify, offrant une interface cohérente pour interagir avec votre parc de serveurs.
Au lieu d'utiliser de nombreux outils distincts, le serveur propose 19 outils basés sur des actions qui utilisent une structure de commande unique avec un champ action. Les utilisateurs peuvent effectuer des tâches telles que la surveillance des déploiements, l'inspection des logs ou l'exécution d'opérations d'urgence. La configuration nécessite de fournir un COOLIFY_URL et un COOLIFY_TOKEN via des variables d'environnement dans la configuration de votre client MCP, ou en enregistrant plusieurs instances dans un fichier JSON local.
La sécurité est intégrée au flux de travail grâce au masquage automatique des secrets pour les données sensibles comme les mots de passe et les tokens. Les actions destructives nécessitent un flag de confirmation explicite pour éviter toute modification accidentelle. Le serveur gère également les problèmes réseau transitoires avec des tentatives automatiques et fournit des codes d'erreur structurés pour aider l'agent IA à se rétablir proprement en cas d'échec.
Ce que vous pouvez faire avec
- 1Déployer et surveiller des applicationsUn agent IA peut déclencher un nouveau déploiement et suivre la progression du build en temps réel.
- 2Dépanner des problèmes d'infrastructureVous pouvez demander à l'agent de scanner l'ensemble de votre parc pour comprendre l'origine d'une panne.
- 3Gérer les workloads de bases de données et de servicesL'agent peut créer et gérer divers workloads, y compris des bases de données et des services.
- 4Exécuter des opérations d'urgenceUn développeur peut ordonner à l'agent d'effectuer des tâches critiques, comme l'arrêt de tous les processus en cours.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Comment installer Coolify MCP
Formats vérifiés le 10 nov. 2026Ajouter à CursorAjouter à GooseInstaller Coolify MCP dans Claude Code
$ claude mcp add awesome-coolify -- npx -y awesome-coolify-mcpInstaller Coolify MCP dans Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"awesome-coolify": {
"command": "npx",
"args": [
"-y",
"awesome-coolify-mcp"
]
}
}
}Installer Coolify MCP dans VS Code
.vscode/mcp.json
{
"servers": {
"awesome-coolify": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"awesome-coolify-mcp"
]
}
}
}Installer Coolify MCP dans VS Code CLI
$ code --add-mcp '{"name":"awesome-coolify","type":"stdio","command":"npx","args":["-y","awesome-coolify-mcp"]}'Installer Coolify MCP dans Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"awesome-coolify": {
"command": "npx",
"args": [
"-y",
"awesome-coolify-mcp"
]
}
}
}Installer Coolify MCP dans Codex
$ codex mcp add awesome-coolify -- npx -y awesome-coolify-mcpInstaller Coolify MCP dans Codex config.toml
~/.codex/config.toml
[mcp_servers.awesome-coolify] command = "npx" args = ["-y", "awesome-coolify-mcp"]
Installer Coolify MCP dans Gemini CLI
$ gemini mcp add -s user awesome-coolify npx -- -y awesome-coolify-mcpInstaller Coolify MCP dans Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"awesome-coolify": {
"command": "npx",
"args": [
"-y",
"awesome-coolify-mcp"
]
}
}
}Outils MCP Coolify 45
Détectés depuis le READMEhealthversionverifyinfrastructure_overviewlistfindappserverscanlogsanalyzeget
| health | — | |
| version | — | |
| verify | — | |
| infrastructure_overview | — | |
| list | — | |
| find | — | |
| app | — | |
| server | — | |
| scan | — | |
| logs | — | |
| analyze | — | |
| get | — |
Afficher les 45 outilsAfficher moins d'outils
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 | — |
Configuration
COOLIFY_MCP_LOGCOOLIFY_TOKENCOOLIFY_URLCOOLIFY_VERIFY_SSL
| Nom | Description | Type |
|---|---|---|
| COOLIFY_MCP_LOG | — | |
| COOLIFY_TOKEN | — | |
| COOLIFY_URL | — | |
| COOLIFY_VERIFY_SSL | — |
Vérifications automatisées
Exécuté le 13 nov. 2026Rapport complet →A passé nos vérifications automatisées. Il ne s'agit pas d'un audit de sécurité : lisez le code et donnez au serveur l'accès le plus restreint dont il a besoin. Fonctionnement des vérifications
- Dépôt source lié et accessibleRéussi
- Licence open source (OSI)Réussi
- Commit ou version publiée au cours de l'année écouléeRéussi
- Nom du package non proche d'un package populaireRéussi
- L'endpoint distant utilise HTTPSNon vérifié
- Les outils destructifs sont étiquetésNon vérifié
- Aucune instruction cachée destinée au modèleRéussi
- Aucun avis critique dans le package ou ses dépendancesRéussi
README
Voir sur 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.) |
Questions sur Coolify MCP
Comment ajouter Coolify MCP à Claude Code ?
Exécutez claude mcp add awesome-coolify -- npx -y awesome-coolify-mcp dans votre terminal. Ajoutez --scope user pour le rendre disponible dans tous les projets.
Comment ajouter Coolify MCP à Cursor ?
Ouvrez ~/.cursor/mcp.json et ajoutez le serveur sous mcpServers, avec la configuration Cursor indiquée dans la section d'installation ci-dessus.
Quels outils Coolify MCP fournit-il ?
Il expose 45 outils, dont health, version, verify, infrastructure_overview, list.
Que puis-je faire avec ce MCP server ?
Vous pouvez vérifier la connectivité, découvrir l'infrastructure, créer des workloads, déployer, suivre les logs, diagnostiquer des incidents et exécuter des opérations d'urgence sur l'ensemble de vos instances Coolify.
Est-il sûr de l'utiliser avec des données sensibles ?
Oui, le serveur inclut un masquage automatique des secrets pour les mots de passe et les tokens, et nécessite une confirmation explicite pour les actions d'urgence destructives.