applicationEnvs
Manage environment variables for an application. Actions: list (secrets masked unless showSecrets), create, update, upsert (create or update by key), bulk_update (pass envs array), delete (needs env_uuid).
LABSCO SUMMARY
The write half can be switched off, and the widest operations ask before they act.
One environment variable separates an agent that can describe the estate from one that can delete a project — but it is on by default, so switching it off is a decision you have to make rather than one made for you. Above that, the estate-wide operations request confirmation on clients that support it, and the stop-everything call states its blast radius when it does. The diagnose tools are the ones worth knowing exist: the app diagnostic folds current status, the latest deployments, the failed deployment's log tail and recent runtime logs into a single call — the sequence you would otherwise assemble by hand while something is down.
What it is
A Coolify client covering the deployment workflow end to end: servers, projects, applications, databases, services, environment variables, storages, scheduled tasks and deployments. Its types and schemas are generated from Coolify's own OpenAPI spec, so tool inputs match what the API actually accepts.
What you get
- getInfrastructureOverview, a one-call summary of servers, projects, applications with a status breakdown, databases, services and running deployments, with getHealth for whether the API is up at all.
- Applications from any source createApplication accepts — a public git repo, a private repo through a GitHub App or an SSH deploy key, a raw Dockerfile, or a prebuilt docker image — with start, stop, restart, update and delete, and an escape hatch validated against the OpenAPI schema for fields not exposed directly.
- Databases across postgresql, mysql, mariadb, mongodb, redis, keydb, dragonfly and clickhouse, each with create, update, delete, start, stop and restart, environment variables, and scheduled backups on a cron frequency with optional S3 storage and retention.
- Services as one-click apps or Docker Compose deployments: createService takes the raw compose file, and since Coolify v4.1 a compose deployment is a service rather than an application.
- deploy by uuid or tag, optionally waiting until every triggered deployment reaches a terminal state and returning a log tail on failure, plus cancelDeployment, listDeployments, listAppDeployments and deletePreview by pull request id.
- Environment variables for applications, databases and services through one action-based tool each: list with secrets masked unless you ask for them, create, update, upsert by key, bulk update and delete.
- storages for persistent volumes and file mounts on any resource, and scheduledTasks for cron jobs with a command, a frequency and their execution history.
- Infrastructure: listServers, createServer against a registered private key, validateServer, updateServer, deleteServer, getServerResources, getServerDomains, SSH private key management, and GitHub App repository and branch listings.
- Diagnostics that aggregate rather than list: diagnoseServer returns the resources on a server with a status breakdown, its domains and suggested next actions; diagnoseApp returns current status, the latest deployments, a log tail from the most recent failed deployment, recent runtime logs and next actions in one call.
- searchDocs, a full-text search over the official Coolify documentation from an index bundled with the server, returning titles, canonical URLs and snippets with no network call.
- Estate-wide operations that ask first: restartProjectApps, redeployProject and stopAllApplications, which states its blast radius on clients that support elicitation.
Requirements
Node 18 or newer, your Coolify instance's API URL in COOLIFY_BASE_URL, and a token from its API settings in COOLIFY_TOKEN. Writes are enabled by default — set COOLIFY_ALLOW_WRITE to false if this install should only ever read. An SSH private key must be registered in Coolify before a server can be created, and a GitHub App configured before a private repository can be deployed through one. Raise your client's tool timeout if you deploy with the wait option, since it polls until the deployment reaches a terminal state.
Setup effort
One command plus a key — npm install -g @fndchagas/coolify-mcp, then supply credentials
USE CASES
01
Working out what is actually running across the estate
One call for servers, projects, applications with their status breakdown, databases, services and anything mid-deployment.
02
Deploying an application out of a private repository
List what the GitHub App can see, create the application against the right branch, and deploy it, waiting for the terminal status.
03
Finding out why an application is down
Ask by uuid, name or domain and get status, recent deployments, the failed deployment's log tail and runtime logs together, with next actions.
04
Standing up a database with its backups scheduled
Create the engine you need, set its environment, and put a cron backup with retention behind it in the same session.
05
Changing configuration without printing the secrets
List the variables masked, upsert the one that changed by key, and redeploy.
06
Bringing an entire project back up after an outage
Restart or redeploy everything in the project in one operation — the tool asks for confirmation first on clients that can.
07
Looking something up in the Coolify docs mid-task
Search the bundled documentation index and get the canonical page URL back without leaving the session.
65 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
cancelDeployment
Cancel a running deployment by UUID.
controlDatabase
Start, stop, or restart a database by UUID.
controlService
Start, stop, or restart a service by UUID.
createApplication
Create a new application. type selects the source: 'public' (public git repo), 'private-github-app' (private repo via GitHub App, needs github_app_uuid), 'private-deploy-key' (private repo via SSH deploy key, needs private_key_uuid), 'dockerfile' (raw Dockerfile content in dockerfile), 'dockerimage' (prebuilt image, needs docker_registry_image_name and ports_exposes). Git-based types also need git_repository, git_branch, and build_pack. All types need project_uuid, server_uuid, and environment_name or environment_uuid (one is enough). Any other Coolify application field (install/build/start commands, base_directory, health checks, resource limits, ...) can be passed in extra; fields not valid for the chosen type are ignored.
createDatabase
Create a database. type selects the engine: postgresql, mysql, mariadb, mongodb, redis, keydb, dragonfly, or clickhouse. Requires project_uuid, server_uuid, and environment_name or environment_uuid (one is enough). Engine-specific fields (versions, credentials, memory limits, ...) can be passed in extra and are validated per engine.
createEnvironment
Create a new environment in a project. Requires the project UUID.
createPrivateKey
Create a new SSH private key. The private_key field should contain the full PEM-encoded key.
createProject
Create a new Coolify project. Returns the project UUID.
createServer
Create a new server. Requires a private key UUID for SSH access.
createService
Create a one-click service (database, cache, etc.) or a Docker Compose deployment (pass docker_compose_raw with the YAML content). Requires project_uuid, server_uuid, and environment_name (or environment_uuid). Since Coolify v4.1, Docker Compose deployments are services, not applications.
databaseBackups
Manage scheduled backups for a database. Actions: list, create, update, delete (backup schedules), list_executions, delete_execution. create/update take frequency (cron expression) plus optional fields (enabled, save_s3, s3_storage_uuid, databases_to_backup, dump_all, retention settings via extra).
databaseEnvs
Manage environment variables for a database. Actions: list (secrets masked unless showSecrets), create, update, bulk_update (pass envs array), delete (needs env_uuid).
deleteApplication
Delete an application by UUID. Optionally delete volumes, configurations, and connected networks.
deleteDatabase
Delete a database by UUID. By default Coolify also deletes configurations, volumes, and connected networks and runs docker cleanup; pass the flags as false to keep them.
deletePreview
Delete a preview deployment of an application by pull request id.
deletePrivateKey
Delete an SSH private key by UUID. Not recoverable from Coolify once gone.
deleteProject
Delete a project by UUID. This will delete all environments and resources in the project.
deleteServer
Delete a server by UUID.
deleteService
Delete a service by UUID. By default Coolify also deletes configurations, volumes, and connected networks and runs docker cleanup; pass the flags as false to keep them.
deploy
Trigger a deployment for an application by UUID or tag. With wait=true, polls until every triggered deployment reaches a terminal status (finished/failed/cancelled) and returns a log tail for failures — raise your MCP client's tool timeout when waiting on long builds.
diagnoseApp
Diagnose an application by UUID, name, or domain. Aggregates current status, the latest deployments, a log tail from the most recent failed deployment, recent runtime logs, and suggested next actions in one call.
diagnoseServer
Diagnose a server by UUID, name, or IP: lists the resources running on it with a status breakdown, configured domains, and suggested next actions.
getApplication
Get application details by UUID (optional field selection).
getDatabase
Get database details by UUID.
getDeployment
Get deployment status and logs by UUID.
getGithubAppBranches
List branches of a repository accessible to a GitHub App.
getGithubAppRepositories
List repositories accessible to a GitHub App.
getHealth
Check that the Coolify API is up (GET /health).
getInfrastructureOverview
One-call summary of the whole Coolify estate: servers, projects, applications (with status breakdown), databases, services, and currently running deployments.
getLogs
Fetch runtime logs for an application.
getPrivateKey
Get an SSH private key's metadata by UUID. The key material is masked unless showSecrets is true.
getServer
Get server details by UUID.
getServerDomains
List all domains configured on a server.
getServerResources
List all resources (applications, databases, services) running on a server.
getService
Get service details by UUID (secrets masked by default; pass showSecrets to reveal).
listAppDeployments
List deployments for an application with pagination (skip/take).
listApplications
List all Coolify applications.
listDatabases
List databases with optional pagination and filters.
listDeployments
List currently running deployments.
listEnvironments
List all environments for a project. Requires the project UUID.
listGithubApps
List all configured GitHub Apps. Used for private repository access.
listPrivateKeys
List all SSH private keys. Keys are used for server authentication and deploy keys.
listProjects
List all Coolify projects. Returns project UUID, name, description, and environments.
listResources
List Coolify resources with optional pagination, summary, and filters.
listServers
List all Coolify servers. Returns server UUID, name, IP, user, port, and proxy type.
listServices
List all Coolify services (one-click apps like databases, caches, etc.).
redeployProject
Trigger a deployment for every application in a project (optionally a single environment). Asks for confirmation on clients that support elicitation.
restartApplication
Restart an application by UUID.
restartProjectApps
Restart every application in a project (optionally a single environment). Asks for confirmation on clients that support elicitation.
scheduledTasks
Manage scheduled tasks (cron jobs) for an application or service. Actions: list, create (name, command, frequency), update, delete, list_executions (all but list/create need task_uuid).
searchDocs
Full-text search across the official Coolify documentation using a local index bundled with this server (no network). Returns page titles, canonical coolify.io/docs URLs, and snippets.
serviceEnvs
Manage environment variables for a service. Actions: list (secrets masked unless showSecrets), create, update, bulk_update (pass envs array), delete (needs env_uuid).
startApplication
Start an application by UUID. Optionally force rebuild.
stopAllApplications
Stop every running application, optionally restricted to one project. Asks for confirmation on clients that support elicitation, stating the blast radius.
stopApplication
Stop an application by UUID.
storages
Manage persistent volumes and file mounts for an application, database, or service. Actions: list, create, update, delete. create needs storage type ('persistent' or 'file') and mount_path; update targets storage_uuid; delete needs storage_uuid.
teams
Read Coolify teams. Actions: list, current, current_members, get (needs id), members (needs id).
updateApplication
Update an application's configuration by UUID. Common fields are exposed; any other Coolify application field (install/build/start commands, health checks, resource limits, static flags, ...) can go in extra and is validated against the OpenAPI schema.
updateDatabase
Update a database's configuration by UUID. Common fields are exposed; any other Coolify database field can go in extra.
updatePrivateKey
Update an SSH private key. The Coolify API identifies the key by its private_key content (required); name and description are optional.
updateProject
Update a project's name or description.
updateServer
Update a server by UUID. Common fields are exposed; any other Coolify server field can go in extra.
updateService
Update a service by UUID. Common fields are exposed; any other Coolify service field (docker_compose_raw, connect_to_docker_network, ...) can go in extra.
validateServer
Validate server connection and configuration by UUID.
BEFORE YOU INSTALL
What to know first
Tools you get
65 tools when we connected. Setting COOLIFY_ALLOW_WRITE=false disables about 35 write tools, including deploy and every create, update and delete. On clients that support elicitation, deletions pause for your confirmation, and tools such as applicationEnvs take an action argument covering several operations.
Requires
- npx on PATH
- Node 18+
- COOLIFY_TOKEN in your environment
- COOLIFY_BASE_URL in your environment
CONTEXT COST
Moderate Standing cost
Rated by the size of the 65 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npm install -g @fndchagas/coolify-mcpMCP Clients
Claude Desktop
Download coolify-mcp.mcpb from the project's latest GitHub release:
CLAUDE DESKTOP · URL
https://github.com/frndchagas/coolify-mcp/releases/latest/download/coolify-mcp.mcpbDrag the file into Settings → Extensions in Claude Desktop. It prompts for your Coolify URL and API token — no Node install, no JSON editing.
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add coolify \
--env COOLIFY_BASE_URL="<YOUR_COOLIFY_URL>/api/v1" \
--env COOLIFY_TOKEN="<YOUR_COOLIFY_TOKEN>" \
-- npx -y @fndchagas/coolify-mcp<YOUR_COOLIFY_URL>/api/v1 is your own Coolify instance's API URL (it ends in /api/v1), and <YOUR_COOLIFY_TOKEN> is an API token created under Settings > API in your Coolify dashboard.
Codex
CODEX · TOML
[mcp_servers.coolify]
command = "npx"
args = ["-y", "@fndchagas/coolify-mcp"]
env = { COOLIFY_BASE_URL = "<YOUR_COOLIFY_URL>/api/v1", COOLIFY_TOKEN = "<YOUR_COOLIFY_TOKEN>" }<YOUR_COOLIFY_URL>/api/v1 is your own Coolify instance's API URL (it ends in /api/v1), and <YOUR_COOLIFY_TOKEN> is an API token created under Settings > API in your Coolify dashboard.
Any MCP client
ANY MCP CLIENT · JSON
{
"mcpServers": {
"coolify": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@fndchagas/coolify-mcp"
],
"env": {
"COOLIFY_BASE_URL": "<YOUR_COOLIFY_URL>/api/v1",
"COOLIFY_TOKEN": "<YOUR_COOLIFY_TOKEN>",
"COOLIFY_ALLOW_WRITE": "true"
}
}
}
}<YOUR_COOLIFY_URL>/api/v1 is your own Coolify instance's API URL (it ends in /api/v1), and <YOUR_COOLIFY_TOKEN> is an API token created under Settings > API in your Coolify dashboard. Set COOLIFY_ALLOW_WRITE to "false" for a read-only install that disables all write operations.
TypeScript MCP SDK
TYPESCRIPT MCP SDK
new StdioClientTransport({ command: 'npx', args: ['-y', '@fndchagas/coolify-mcp'], env: { COOLIFY_BASE_URL: '<YOUR_COOLIFY_URL>/api/v1', COOLIFY_TOKEN: '<YOUR_COOLIFY_TOKEN>' } })<YOUR_COOLIFY_URL>/api/v1 is your own Coolify instance's API URL (it ends in /api/v1), and <YOUR_COOLIFY_TOKEN> is an API token created under Settings > API in your Coolify dashboard.
