Labsco
frndchagas logo

Coolify MCP

★ 3

from frndchagas

MCP server for Coolify API operations.

🔥🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#automation#database#devops#git#security

coolify-mcp

npm downloads

MCP server for Coolify API - enables full deployment workflows from zero to production.

Features

  • Full Deployment Workflow: Create projects, environments, servers, and applications from scratch
  • 6 Application Types: Public git, GitHub App, Deploy Key, Dockerfile, Docker Image, Docker Compose
  • Environment Management: Full CRUD for environment variables with secret masking
  • Deployment Control: Deploy, start, stop, restart applications
  • Security: Write protection, secret redaction, log sanitization
  • 38 Tools: Complete coverage of Coolify API operations

Environment Variables

VariableDefaultDescription
COOLIFY_BASE_URLrequiredCoolify API URL (e.g., https://coolify.example.com/api/v1)
COOLIFY_TOKENrequiredAPI token from Coolify Settings > API
COOLIFY_ALLOW_WRITEtrueEnable write operations (create, update, delete, deploy)
COOLIFY_ALLOW_UNSAFE_LOGSfalseAllow raw logs without redaction
COOLIFY_STRICT_VERSIONfalseFail on API version mismatch
MCP_TRANSPORTstdioTransport: stdio, http, both
PORT7331HTTP port (when using http transport)

Tools Reference

Projects & Environments

ToolDescriptionWrite
listProjectsList all projects
createProjectCreate a new project✓
updateProjectUpdate project name/description✓
deleteProjectDelete a project and all its resources✓
listEnvironmentsList environments in a project
createEnvironmentCreate a new environment✓

Servers & Infrastructure

ToolDescriptionWrite
listServersList all servers
getServerGet server details
createServerCreate a new server✓
validateServerValidate server connection
listPrivateKeysList SSH private keys
createPrivateKeyCreate a new SSH key✓
listGithubAppsList configured GitHub Apps

Applications - Read

ToolDescription
listApplicationsList all applications (summarized by default)
getApplicationGet application details (secrets masked by default)
getLogsGet application runtime logs

Applications - Create

ToolDescriptionWrite
createPublicApplicationCreate from public git repository✓
createPrivateGithubAppApplicationCreate using GitHub App✓
createPrivateDeployKeyApplicationCreate using SSH deploy key✓
createDockerfileApplicationCreate from Dockerfile content✓
createDockerImageApplicationCreate from Docker image✓
createDockerComposeApplicationCreate from Docker Compose✓

Applications - Manage

ToolDescriptionWrite
updateApplicationUpdate application configuration✓
deleteApplicationDelete an application✓
startApplicationStart an application✓
stopApplicationStop an application✓
restartApplicationRestart an application✓

Environment Variables

ToolDescriptionWrite
listEnvsList env vars (secrets masked by default)
createEnvCreate a new env var✓
upsertEnvCreate or update env var by key✓
updateEnvUpdate an existing env var✓
deleteEnvDelete an env var✓

Deployments

ToolDescriptionWrite
deployTrigger a deployment✓
listDeploymentsList running deployments
getDeploymentGet deployment status and logs
listAppDeploymentsList deployments for an application
cancelDeploymentCancel a running deployment✓

Databases & Services

ToolDescriptionWrite
listDatabasesList all databases
getDatabaseGet database details
listServicesList one-click services
createServiceCreate a one-click service✓

Other

ToolDescription
listResourcesList all resources with filtering

Security Features

Write Protection

Disable all write operations:

COOLIFY_ALLOW_WRITE=false

Secret Masking

  • Environment variable values are masked by default
  • Database credentials are redacted
  • Use showSecrets: true only when necessary

Log Sanitization

Logs are sanitized to remove sensitive data. Control with logMode:

  • safe (default): Redacts common secret patterns
  • strict: More aggressive redaction
  • raw: No redaction (requires COOLIFY_ALLOW_UNSAFE_LOGS=true)

Development

git clone https://github.com/frndchagas/coolify-mcp.git
cd coolify-mcp
npm install
npm run dev

Scripts

npm run dev            # Run in development mode
npm run build          # Build TypeScript
npm run generate       # Regenerate types from OpenAPI
npm run fetch:openapi  # Fetch latest OpenAPI spec
npm run update         # Fetch + regenerate

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 update

Registry Listings

MCP Client Examples

HTTP Client

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: 'coolify.listApplications',
  arguments: {},
});
console.log(apps.structuredContent);

// Deploy an application
const deploy = await client.callTool({
  name: 'coolify.deploy',
  arguments: { uuid: 'your-app-uuid' },
});
console.log(deploy.structuredContent);

await client.close();

Stdio Client

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: 'coolify.getApplication',
  arguments: { uuid: 'your-app-uuid' },
});
console.log(result.structuredContent);

await client.close();