Coolify MCP
MCP server for Coolify API operations.
Open source Open in the app JSON README (API)
About
MCP server for Coolify API operations.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- frndchagas
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 2.3.1
- Stars
- 3
- Forks
- 1
- Last push
- 2026-09-08T01:24:40Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:48
- Updated
- 2026-08-29 03:02:48
- Origin id
io.github.frndchagas/coolify-mcp
README
# coolify-mcp
[](https://www.npmjs.com/package/@fndchagas/coolify-mcp)
[](https://www.npmjs.com/package/@fndchagas/coolify-mcp)
[](LICENSE)
[](package.json)
[](https://www.typescriptlang.org/)
[](https://github.com/frndchagas/coolify-mcp/actions/workflows/ci.yml)
[](https://glama.ai/mcp/servers/frndchagas/coolify-mcp)
MCP server for Coolify API - enables full deployment workflows from zero to production.
Targets 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.
## Features
- **Full Deployment Workflow**: Create projects, environments, servers, and applications from scratch
- **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)
- **Environment Management**: Full CRUD for environment variables with secret masking
- **Deployment Control**: Deploy (optionally waiting for the terminal status, with a log tail on failure), start, stop, restart applications
- **Diagnostics**: `diagnoseApp` finds an app by UUID, name, or domain and aggregates status, recent deployments, failure log tails, runtime logs, and suggested next actions
- **Docs Search**: `searchDocs` runs full-text search across the official Coolify documentation from a bundled local index — no network needed
- **Security**: Write protection, secret redaction, and MCP annotations (`readOnlyHint`/`destructiveHint`) so clients can auto-approve reads and gate destructive calls
- **Near-full API coverage**: databases (8 engines, backups, envs), services, storages, scheduled tasks, teams, previews, servers, SSH keys, and GitHub Apps
- **Token-efficient**: 65 tools whose definitions cost ~9k tokens of context, with strict runtime validation against schemas generated from Coolify's OpenAPI spec
## Requirements
- Node 18+
- A Coolify API token (Settings > API in your Coolify dashboard)
## Install
**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.
**Via npm:**
```bash
npm install -g @fndchagas/coolify-mcp
# or
npx -y @fndchagas/coolify-mcp
```
## Quick Start
### Claude Code CLI
```bash
claude mcp add coolify \
--env COOLIFY_BASE_URL="https://coolify.example.com/api/v1" \
--env COOLIFY_TOKEN="<token>" \
-- npx -y @fndchagas/coolify-mcp
```
### OpenAI Codex CLI
```bash
codex mcp add coolify \
--env COOLIFY_BASE_URL="https://coolify.example.com/api/v1" \
--env COOLIFY_TOKEN="<token>" \
-- npx -y @fndchagas/coolify-mcp
```
Or edit `~/.codex/config.toml`:
```toml
[mcp_servers.coolify]
command = "npx"
args = ["-y", "@fndchagas/coolify-mcp"]
env = { COOLIFY_BASE_URL = "https://coolify.example.com/api/v1", COOLIFY_TOKEN = "<token>" }
```
### Manual Configuration (`~/.mcp.json`)
```json
{
"mcpServers": {
"coolify": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@fndchagas/coolify-mcp"],
"env": {
"COOLIFY_BASE_URL": "https://coolify.example.com/api/v1",
"COOLIFY_TOKEN": "<token>",
"COOLIFY_ALLOW_WRITE": "true"
}
}
}
}
```
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `COOLIFY_BASE_URL` | required | Coolify API URL (e.g., `https://coolify.example.com/api/v1`) |
| `COOLIFY_TOKEN` | required | API token from Coolify Settings > API |
| `COOLIFY_ALLOW_WRITE` | `true` | Enable write operations (create, update, delete, deploy) |
| `COOLIFY_STRICT_VERSION` | `false` | Fail on API version mismatch |
| `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) |
| `MCP_TRANSPORT` | `stdio` | Transport: `stdio`, `http`, `both` |
| `PORT` | `7331` | HTTP port (when using http transport) |
| `MCP_HTTP_TOKEN` | unset | Bearer token required on `/mcp` requests (HTTP transport). Setting it also switches the default bind to `0.0.0.0` |
| `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 |
## Deploy from Zero
With this MCP, you can deploy an application from scratch:
```
1. listProjects / createProject → Get or create a project
2. listEnvironments / createEnvironment → Get or create an environment
3. listServers / createServer → Get or create a server
4. listPrivateKeys / createPrivateKey → Get or create SSH keys (if needed)
5. createApplication (type: public) → Create the application
6. applicationEnvs (action: upsert) → Configure environment variables
7. deploy → Trigger deployment
```
## Tools Reference
### Projects & Environments
| Tool | Description | Write |
|------|-------------|-------|
| `listProjects` | List all projects | |
| `createProject` | Create a new project | ✓ |
| `updateProject` | Update project name/description | ✓ |
| `deleteProject` | Delete a project and all its resources | ✓ |
| `listEnvironments` | List environments in a project | |
| `createEnvironment` | Create a new environment | ✓ |
### Servers & Infrastructure
| Tool | Description | Write |
|------|-------------|-------|
| `listServers` | List all servers | |
| `getServer` | Get server details | |
| `createServer` | Create a new server | ✓ |
| `validateServer` | Validate server connection | |
| `listPrivateKeys` | List SSH private keys | |
| `createPrivateKey` | Create a new SSH key | ✓ |
| `listGithubApps` | List configured GitHub Apps | |
### Applications - Read
| Tool | Description |
|------|-------------|
| `listApplications` | List all applications (summarized by default) |
| `getApplication` | Get application details (secrets masked by default) |
| `getLogs` | Get application runtime logs |
### Applications - Create
| Tool | Description | Write |
|------|-------------|-------|
| `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. | ✓ |
> Docker Compose deployments are created with `createService` passing `docker_compose_raw` — since Coolify v4.1 they are services, not applications.
### Applications - Manage
| Tool | Description | Write |
|------|-------------|-------|
| `updateApplication` | Update application configuration | ✓ |
| `deleteApplication` | Delete an application | ✓ |
| `startApplication` | Start an application | ✓ |
| `stopApplication` | Stop an application | ✓ |
| `restartApplication` | Restart an application | ✓ |
### Environment Variables
| Tool | Description | Write |
|------|-------------|-------|
| `applicationEnvs` | Manage application env vars: list (masked by default), create, update, upsert by key, bulk_update, delete | ✓ |
> Database and service env vars have their own tools: `databaseEnvs` and `serviceEnvs`.
### Deployments
| Tool | Description | Write |
|------|-------------|-------|
| `deploy` | Trigger a deployment; `wait: true` polls to the terminal status and returns a log tail on failure | ✓ |
| `diagnoseApp` | Diagnose an app by UUID, name, or domain: status, recent deployments, failure log tail, runtime logs, hints | |
| `diagnoseServer` | Diagnose a server by UUID, name, or IP: resource status breakdown, domains, hints | |
| `listDeployments` | List running deployments | |
| `getDeployment` | Get deployment status and logs | |
| `listAppDeployments` | List deployments for an application | |
| `cancelDeployment` | Cancel a running deployment | ✓ |
### Databases
| Tool | Description | Write |
|------|-------------|-------|
| `listDatabases` | List all databases | |
| `getDatabase` | Get database details | |
| `createDatabase` | Create a database; `type` selects the engine: postgresql, mysql, mariadb, mongodb, redis, keydb, dragonfly, clickhouse | ✓ |
| `updateDatabase` | Update database configuration | ✓ |
| `deleteDatabase` | Delete a database (volumes/configs deleted by default) | ✓ |
| `controlDatabase` | Start, stop, or restart a database | ✓ |
| `databaseBackups` | Manage backup schedules and executions (list/create/update/delete/list_executions/delete_execution) | ✓ |
| `databaseEnvs` | Manage database env vars (list/create/update/bulk_update/delete) | ✓ |
### Services
| Tool | Description | Write |
|------|-------------|-------|
| `listServices` | List services | |
| `getService` | Get service details (secrets masked by default) | |
| `createService` | Create a one-click service or Docker Compose deployment | ✓ |
| `updateService` | Update a service | ✓ |
| `deleteService` | Delete a service | ✓ |
| `controlService` | Start, stop, or restart a service | ✓ |
| `serviceEnvs` | Manage service env vars (list/create/update/bulk_update/delete) | ✓ |
### Storages, Scheduled Tasks & Previews
| Tool | Description | Write |
|------|-------------|-------|
| `storages` | Manage persistent volumes and file mounts for applications, databases, and services | ✓ |
| `scheduledTasks` | Manage cron tasks for applications and services, including execution history | ✓ |
| `deletePreview` | Delete a preview deployment by pull request id | ✓ |
### Teams, Servers & Git
| Tool | Description | Write |
|------|-------------|-------|
| `teams` | List teams, get current team, and list members | |
| `updateServer` | Update server configuration | ✓ |
| `deleteServer` | Delete a server | ✓ |
| `getServerResources` | List resources running on a server | |
| `getServerDomains` | List domains configured on a server | |
| `getPrivateKey` | Get SSH key metadata (key material masked by default) | |
| `updatePrivateKey` | Update an SSH private key | ✓ |
| `deletePrivateKey` | Delete an SSH private key | ✓ |
| `getGithubAppRepositories` | List repositories accessible to a GitHub App | |
| `getGithubAppBranches` | List branches of a repository | |
### Batch Operations
| Tool | Description | Write |
|------|-------------|-------|
| `getInfrastructureOverview` | One-call summary of servers, projects, applications (status breakdown), databases, services, and running deployments | |
| `restartProjectApps` | Restart every application in a project or environment (asks for confirmation) | ✓ |
| `redeployProject` | Trigger a deployment for every application in a project or environment (asks for confirmation) | ✓ |
| `stopAllApplications` | Emergency stop of all running applications, optionally per project (asks for confirmation, stating the blast radius) | ✓ |
### Other
| Tool | Description |
|------|-------------|
| `listResources` | List all resources with filtering |
| `searchDocs` | Full-text search across the official Coolify docs (bundled index, no network) |
| `getHealth` | Check that the Coolify API is up |
## Security Features
### Write Protection
Disable all write operations:
```bash
COOLIFY_ALLOW_WRITE=false
```
### Secret Masking
- Environment variable values are masked by default
- Database credentials are redacted
- Use `showSecrets: true` only when necessary
### HTTP Transport Hardening
The 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.
### Human Confirmation on Destructive Deletes
On 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.
## Development
```bash
git clone https://github.com/frndchagas/coolify-mcp.git
cd coolify-mcp
npm install
npm run dev
```
### Scripts
```bash
npm run dev # Run in development mode
npm run build # Build TypeScript
npm run generate # Fetch the pinned OpenAPI spec and regenerate types
```
### Pinned Coolify Version
Version is defined in `src/coolify/constants.ts`. To update:
1. Edit `COOLIFY_VERSION` in `src/coolify/constants.ts`
2. Run `npm run generate`
## Registry Listings
- MCP Registry: [`io.github.frndchagas/coolify-mcp`](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.frndchagas%2Fcoolify-mcp)
## MCP Client Examples
### HTTP Client
```ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const client = new Client({ name: 'coolify-client', version: '1.0.0' });
const transport = new StreamableHTTPClientTransport(
new URL('http://localhost:7331/mcp')
);
await client.connect(transport);
// List all applications
const apps = await client.callTool({
name: 'listApplications',
arguments: {},
});
console.log(apps.structuredContent);
// Deploy an application
const deploy = await client.callTool({
name: 'deploy',
arguments: { uuid: 'your-app-uuid' },
});
console.log(deploy.structuredContent);
await client.close();
```
### Stdio Client
```ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
const client = new Client({ name: 'coolify-client', version: '1.0.0' });
const transport = new StdioClientTransport({
command: 'npx',
args: ['-y', '@fndchagas/coolify-mcp'],
env: {
COOLIFY_BASE_URL: 'https://coolify.example.com/api/v1',
COOLIFY_TOKEN: '<token>',
},
});
await client.connect(transport);
const result = await client.callTool({
name: 'getApplication',
arguments: { uuid: 'your-app-uuid' },
});
console.log(result.structuredContent);
await client.close();
```
## License
MIT