{
  "markdown": "# coolify-mcp\n\n[![npm version](https://img.shields.io/npm/v/@fndchagas/coolify-mcp.svg)](https://www.npmjs.com/package/@fndchagas/coolify-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/@fndchagas/coolify-mcp.svg)](https://www.npmjs.com/package/@fndchagas/coolify-mcp)\n[![license](https://img.shields.io/npm/l/@fndchagas/coolify-mcp.svg)](LICENSE)\n[![node version](https://img.shields.io/node/v/@fndchagas/coolify-mcp.svg)](package.json)\n[![typescript](https://img.shields.io/badge/TypeScript-5.9.3-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![CI](https://github.com/frndchagas/coolify-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/frndchagas/coolify-mcp/actions/workflows/ci.yml)\n[![Glama score](https://glama.ai/mcp/servers/frndchagas/coolify-mcp/badges/score.svg)](https://glama.ai/mcp/servers/frndchagas/coolify-mcp)\n\nMCP server for Coolify API - enables full deployment workflows from zero to production.\n\n![coolify-mcp demo](docs/demo.gif)\n\nTargets the **Coolify v4.3.10** API. Types and schemas are generated directly from Coolify's official OpenAPI spec, so tool inputs always match what the API actually accepts.\n\n## Features\n\n- **Full Deployment Workflow**: Create projects, environments, servers, and applications from scratch\n- **5 Application Types**: one `createApplication` tool covers public git, GitHub App, Deploy Key, Dockerfile, and Docker Image sources — plus Docker Compose deployments via `createService` (since Coolify v4.1, compose deployments are services)\n- **Environment Management**: Full CRUD for environment variables with secret masking\n- **Deployment Control**: Deploy (optionally waiting for the terminal status, with a log tail on failure), start, stop, restart applications\n- **Diagnostics**: `diagnoseApp` finds an app by UUID, name, or domain and aggregates status, recent deployments, failure log tails, runtime logs, and suggested next actions\n- **Docs Search**: `searchDocs` runs full-text search across the official Coolify documentation from a bundled local index — no network needed\n- **Security**: Write protection, secret redaction, and MCP annotations (`readOnlyHint`/`destructiveHint`) so clients can auto-approve reads and gate destructive calls\n- **Near-full API coverage**: databases (8 engines, backups, envs), services, storages, scheduled tasks, teams, previews, servers, SSH keys, and GitHub Apps\n- **Token-efficient**: 65 tools whose definitions cost ~9k tokens of context, with strict runtime validation against schemas generated from Coolify's OpenAPI spec\n\n## Requirements\n\n- Node 18+\n- A Coolify API token (Settings > API in your Coolify dashboard)\n\n## Install\n\n**Claude Desktop, one-click:** download [`coolify-mcp.mcpb`](https://github.com/frndchagas/coolify-mcp/releases/latest/download/coolify-mcp.mcpb) from the latest release and drag it into **Settings → Extensions**. You'll be prompted for your Coolify URL and token — no Node install, no JSON editing.\n\n**Via npm:**\n\n```bash\nnpm install -g @fndchagas/coolify-mcp\n# or\nnpx -y @fndchagas/coolify-mcp\n```\n\n## Quick Start\n\n### Claude Code CLI\n\n```bash\nclaude mcp add coolify \\\n  --env COOLIFY_BASE_URL=\"https://coolify.example.com/api/v1\" \\\n  --env COOLIFY_TOKEN=\"<token>\" \\\n  -- npx -y @fndchagas/coolify-mcp\n```\n\n### OpenAI Codex CLI\n\n```bash\ncodex mcp add coolify \\\n  --env COOLIFY_BASE_URL=\"https://coolify.example.com/api/v1\" \\\n  --env COOLIFY_TOKEN=\"<token>\" \\\n  -- npx -y @fndchagas/coolify-mcp\n```\n\nOr edit `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.coolify]\ncommand = \"npx\"\nargs = [\"-y\", \"@fndchagas/coolify-mcp\"]\nenv = { COOLIFY_BASE_URL = \"https://coolify.example.com/api/v1\", COOLIFY_TOKEN = \"<token>\" }\n```\n\n### Manual Configuration (`~/.mcp.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"coolify\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@fndchagas/coolify-mcp\"],\n      \"env\": {\n        \"COOLIFY_BASE_URL\": \"https://coolify.example.com/api/v1\",\n        \"COOLIFY_TOKEN\": \"<token>\",\n        \"COOLIFY_ALLOW_WRITE\": \"true\"\n      }\n    }\n  }\n}\n```\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `COOLIFY_BASE_URL` | required | Coolify API URL (e.g., `https://coolify.example.com/api/v1`) |\n| `COOLIFY_TOKEN` | required | API token from Coolify Settings > API |\n| `COOLIFY_ALLOW_WRITE` | `true` | Enable write operations (create, update, delete, deploy) |\n| `COOLIFY_STRICT_VERSION` | `false` | Fail on API version mismatch |\n| `COOLIFY_MCP_ELICITATION` | `on` | Set to `off` to skip human confirmation on destructive deletes (escape hatch for clients that advertise elicitation but do not implement it) |\n| `MCP_TRANSPORT` | `stdio` | Transport: `stdio`, `http`, `both` |\n| `PORT` | `7331` | HTTP port (when using http transport) |\n| `MCP_HTTP_TOKEN` | unset | Bearer token required on `/mcp` requests (HTTP transport). Setting it also switches the default bind to `0.0.0.0` |\n| `MCP_HTTP_HOST` | `127.0.0.1` (`0.0.0.0` with token) | Interface the HTTP transport binds to. Binding beyond loopback without a token logs a loud warning |\n\n## Deploy from Zero\n\nWith this MCP, you can deploy an application from scratch:\n\n```\n1. listProjects / createProject       → Get or create a project\n2. listEnvironments / createEnvironment → Get or create an environment\n3. listServers / createServer         → Get or create a server\n4. listPrivateKeys / createPrivateKey → Get or create SSH keys (if needed)\n5. createApplication (type: public)   → Create the application\n6. applicationEnvs (action: upsert)   → Configure environment variables\n7. deploy                             → Trigger deployment\n```\n\n## Tools Reference\n\n### Projects & Environments\n\n| Tool | Description | Write |\n|------|-------------|-------|\n| `listProjects` | List all projects | |\n| `createProject` | Create a new project | ✓ |\n| `updateProject` | Update project name/description | ✓ |\n| `deleteProject` | Delete a project and all its resources | ✓ |\n| `listEnvironments` | List environments in a project | |\n| `createEnvironment` | Create a new environment | ✓ |\n\n### Servers & Infrastructure\n\n| Tool | Description | Write |\n|------|-------------|-------|\n| `listServers` | List all servers | |\n| `getServer` | Get server details | |\n| `createServer` | Create a new server | ✓ |\n| `validateServer` | Validate server connection | |\n| `listPrivateKeys` | List SSH private keys | |\n| `createPrivateKey` | Create a new SSH key | ✓ |\n| `listGithubApps` | List configured GitHub Apps | |\n\n### Applications - Read\n\n| Tool | Description |\n|------|-------------|\n| `listApplications` | List all applications (summarized by default) |\n| `getApplication` | Get application details (secrets masked by default) |\n| `getLogs` | Get application runtime logs |\n\n### Applications - Create\n\n| Tool | Description | Write |\n|------|-------------|-------|\n| `createApplication` | Create an application; `type` selects the source: `public`, `private-github-app`, `private-deploy-key`, `dockerfile`, or `dockerimage`. Long-tail fields go in `extra` and are validated per type. | ✓ |\n\n> Docker Compose deployments are created with `createService` passing `docker_compose_raw` — since Coolify v4.1 they are services, not applications.\n\n### Applications - Manage\n\n| Tool | Description | Write |\n|------|-------------|-------|\n| `updateApplication` | Update application configuration | ✓ |\n| `deleteApplication` | Delete an application | ✓ |\n| `startApplication` | Start an application | ✓ |\n| `stopApplication` | Stop an application | ✓ |\n| `restartApplication` | Restart an application | ✓ |\n\n### Environment Variables\n\n| Tool | Description | Write |\n|------|-------------|-------|\n| `applicationEnvs` | Manage application env vars: list (masked by default), create, update, upsert by key, bulk_update, delete | ✓ |\n\n> Database and service env vars have their own tools: `databaseEnvs` and `serviceEnvs`.\n\n### Deployments\n\n| Tool | Description | Write |\n|------|-------------|-------|\n| `deploy` | Trigger a deployment; `wait: true` polls to the terminal status and returns a log tail on failure | ✓ |\n| `diagnoseApp` | Diagnose an app by UUID, name, or domain: status, recent deployments, failure log tail, runtime logs, hints | |\n| `diagnoseServer` | Diagnose a server by UUID, name, or IP: resource status breakdown, domains, hints | |\n| `listDeployments` | List running deployments | |\n| `getDeployment` | Get deployment status and logs | |\n| `listAppDeployments` | List deployments for an application | |\n| `cancelDeployment` | Cancel a running deployment | ✓ |\n\n### Databases\n\n| Tool | Description | Write |\n|------|-------------|-------|\n| `listDatabases` | List all databases | |\n| `getDatabase` | Get database details | |\n| `createDatabase` | Create a database; `type` selects the engine: postgresql, mysql, mariadb, mongodb, redis, keydb, dragonfly, clickhouse | ✓ |\n| `updateDatabase` | Update database configuration | ✓ |\n| `deleteDatabase` | Delete a database (volumes/configs deleted by default) | ✓ |\n| `controlDatabase` | Start, stop, or restart a database | ✓ |\n| `databaseBackups` | Manage backup schedules and executions (list/create/update/delete/list_executions/delete_execution) | ✓ |\n| `databaseEnvs` | Manage database env vars (list/create/update/bulk_update/delete) | ✓ |\n\n### Services\n\n| Tool | Description | Write |\n|------|-------------|-------|\n| `listServices` | List services | |\n| `getService` | Get service details (secrets masked by default) | |\n| `createService` | Create a one-click service or Docker Compose deployment | ✓ |\n| `updateService` | Update a service | ✓ |\n| `deleteService` | Delete a service | ✓ |\n| `controlService` | Start, stop, or restart a service | ✓ |\n| `serviceEnvs` | Manage service env vars (list/create/update/bulk_update/delete) | ✓ |\n\n### Storages, Scheduled Tasks & Previews\n\n| Tool | Description | Write |\n|------|-------------|-------|\n| `storages` | Manage persistent volumes and file mounts for applications, databases, and services | ✓ |\n| `scheduledTasks` | Manage cron tasks for applications and services, including execution history | ✓ |\n| `deletePreview` | Delete a preview deployment by pull request id | ✓ |\n\n### Teams, Servers & Git\n\n| Tool | Description | Write |\n|------|-------------|-------|\n| `teams` | List teams, get current team, and list members | |\n| `updateServer` | Update server configuration | ✓ |\n| `deleteServer` | Delete a server | ✓ |\n| `getServerResources` | List resources running on a server | |\n| `getServerDomains` | List domains configured on a server | |\n| `getPrivateKey` | Get SSH key metadata (key material masked by default) | |\n| `updatePrivateKey` | Update an SSH private key | ✓ |\n| `deletePrivateKey` | Delete an SSH private key | ✓ |\n| `getGithubAppRepositories` | List repositories accessible to a GitHub App | |\n| `getGithubAppBranches` | List branches of a repository | |\n\n### Batch Operations\n\n| Tool | Description | Write |\n|------|-------------|-------|\n| `getInfrastructureOverview` | One-call summary of servers, projects, applications (status breakdown), databases, services, and running deployments | |\n| `restartProjectApps` | Restart every application in a project or environment (asks for confirmation) | ✓ |\n| `redeployProject` | Trigger a deployment for every application in a project or environment (asks for confirmation) | ✓ |\n| `stopAllApplications` | Emergency stop of all running applications, optionally per project (asks for confirmation, stating the blast radius) | ✓ |\n\n### Other\n\n| Tool | Description |\n|------|-------------|\n| `listResources` | List all resources with filtering |\n| `searchDocs` | Full-text search across the official Coolify docs (bundled index, no network) |\n| `getHealth` | Check that the Coolify API is up |\n\n## Security Features\n\n### Write Protection\n\nDisable all write operations:\n\n```bash\nCOOLIFY_ALLOW_WRITE=false\n```\n\n### Secret Masking\n\n- Environment variable values are masked by default\n- Database credentials are redacted\n- Use `showSecrets: true` only when necessary\n\n### HTTP Transport Hardening\n\nThe HTTP transport binds to `127.0.0.1` by default. To expose it beyond loopback, set `MCP_HTTP_TOKEN` — every request to `/mcp` must then carry `Authorization: Bearer <token>` (checked in constant time) — and the bind switches to `0.0.0.0` (override with `MCP_HTTP_HOST`). Binding to a non-loopback host without a token logs a loud warning: anyone who can reach the port controls your Coolify instance.\n\n### Human Confirmation on Destructive Deletes\n\nOn MCP clients that support [elicitation](https://modelcontextprotocol.io/specification/2025-06-18/changelog) (Claude Code, VS Code Copilot), deleting a project, application, database, service, server, or private key asks **you** to confirm first, stating what will be lost. Clients without elicitation behave exactly as before. A decline, cancel, or timeout aborts the call; set `COOLIFY_MCP_ELICITATION=off` to disable the prompts entirely.\n\n## Development\n\n```bash\ngit clone https://github.com/frndchagas/coolify-mcp.git\ncd coolify-mcp\nnpm install\nnpm run dev\n```\n\n### Scripts\n\n```bash\nnpm run dev            # Run in development mode\nnpm run build          # Build TypeScript\nnpm run generate       # Fetch the pinned OpenAPI spec and regenerate types\n```\n\n### Pinned Coolify Version\n\nVersion is defined in `src/coolify/constants.ts`. To update:\n\n1. Edit `COOLIFY_VERSION` in `src/coolify/constants.ts`\n2. Run `npm run generate`\n\n## Registry Listings\n\n- MCP Registry: [`io.github.frndchagas/coolify-mcp`](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.frndchagas%2Fcoolify-mcp)\n\n## MCP Client Examples\n\n### HTTP Client\n\n```ts\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';\n\nconst client = new Client({ name: 'coolify-client', version: '1.0.0' });\nconst transport = new StreamableHTTPClientTransport(\n  new URL('http://localhost:7331/mcp')\n);\n\nawait client.connect(transport);\n\n// List all applications\nconst apps = await client.callTool({\n  name: 'listApplications',\n  arguments: {},\n});\nconsole.log(apps.structuredContent);\n\n// Deploy an application\nconst deploy = await client.callTool({\n  name: 'deploy',\n  arguments: { uuid: 'your-app-uuid' },\n});\nconsole.log(deploy.structuredContent);\n\nawait client.close();\n```\n\n### Stdio Client\n\n```ts\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';\n\nconst client = new Client({ name: 'coolify-client', version: '1.0.0' });\nconst transport = new StdioClientTransport({\n  command: 'npx',\n  args: ['-y', '@fndchagas/coolify-mcp'],\n  env: {\n    COOLIFY_BASE_URL: 'https://coolify.example.com/api/v1',\n    COOLIFY_TOKEN: '<token>',\n  },\n});\n\nawait client.connect(transport);\n\nconst result = await client.callTool({\n  name: 'getApplication',\n  arguments: { uuid: 'your-app-uuid' },\n});\nconsole.log(result.structuredContent);\n\nawait client.close();\n```\n\n## License\n\nMIT\n",
  "bytes": 15068,
  "sha": "3457bf15fb9e0ef613e188f404c9539e7210e7276f217d3b2030e51aa07fac41",
  "repo_slug": "frndchagas/coolify-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_frndchagas_coolify_mcp_21b702c4/readme"
}