coolify-mcp

MCP server for Coolify — enables AI assistants to manage Coolify deployments through the Model Context Protocol.

Purpose

coolify-mcp is a platform adapter that exposes Coolify's REST API as MCP tools and resources. It enables AI coding assistants (Claude Code, OpenCode, Codex, and others) to inspect, create, configure, and monitor deployments on Coolify without requiring the user to navigate the Coolify dashboard.

Why It Exists

Deploying applications through a dashboard is slow and error-prone. When AI assistants can programmatically interact with Coolify, they can:

• Inspect a codebase and recommend a deployment strategy (project detection)
• Generate a deploy.intent.yaml manifest
• Create applications with correct settings automatically
• Configure environment variables and secrets
• Trigger deployments and poll for status
• Read logs to diagnose failures

This MCP server bridges the gap between an AI assistant's natural language understanding and Coolify's API-driven deployment platform.

Key Features

• 15 MCP tools covering full application lifecycle
• Project detection — analyzes local code to recommend deployment strategy
• Zod schema validation — all tool inputs validated, clear error messages
• TypeScript-first — full type safety throughout
• Read/write separation — read-only tools safe for exploration; mutating tools require confirmation

Architecture Summary

┌─────────────────┐     MCP       ┌──────────────────┐     REST API     ┌─────────────┐
│  AI Assistant   │◄──────────────►│    coolify-mcp    │◄─────────────────►│   Coolify   │
│                 │                │   (TypeScript)    │                   │   Server    │
└─────────────────┘                └──────────────────┘                   └─────────────┘

Components

Component	Location	Purpose
MCP Server	src/server/	Protocol handler, tool routing
Tools	src/tools/	15 tool implementations
API Client	src/adapters/coolify-api/	Typed Coolify API client
Project Detection	src/detection/	Local codebase analysis
Schemas	src/schemas/	TypeScript types + Zod validation

Supported Tools

Project Management

Tool	Description
list_projects	List all Coolify projects

Application Management

Tool	Description
list_applications	List applications with filtering
get_application	Get application details

Application Creation

Tool	Description
create_application_public_repo	Create from public Git repository
create_application_private_repo_deploy_key	Private repo with deploy key
create_application_private_repo_github_app	Private repo via GitHub App
create_application_dockerfile	Create with custom Dockerfile
create_application_docker_image	Create from prebuilt container image
create_application_compose	Create Docker Compose application

Environment Variables

Tool	Description
list_envs	List environment variables
set_env	Set a single environment variable
bulk_set_envs	Set multiple environment variables

Deployment Operations

Tool	Description
trigger_deploy	Trigger a new deployment
get_logs	Get deployment or application logs
get_deployment_status	Get deployment status

Project Detection

Tool	Description
detect_project_type	Analyze codebase, recommend strategy

Project Structure

coolify-mcp/
├── src/
│   ├── server/                  # MCP server implementation
│   ├── tools/                    # MCP tool definitions (15 tools)
│   ├── adapters/coolify-api/     # Coolify API client
│   ├── detection/                # Project type detection logic
│   ├── schemas/                 # TypeScript + Zod schemas
│   └── prompts/                 # Prompt templates
├── docs/
│   ├── coolify-api-mapping.md   # Tool → API endpoint mapping
│   └── detection-rules.md        # Project detection heuristics
├── examples/                     # JSON example payloads
├── tests/                       # Unit and integration tests
├── package.json
└── README.md

Installation

Prerequisites

• Node.js 18+
• A running Coolify instance (v4.x recommended)
• Coolify API key

Build from Source

git clone https://github.com/REPLACE_WITH_ORG/coolify-mcp
cd coolify-mcp
npm install
npm run build

Configuration

Environment Variables

export COOLIFY_URL="http://your-coolify-instance:3000"
export COOLIFY_API_KEY="your-api-key"

Claude Code Setup

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["./path/to/coolify-mcp/dist/server.js"],
      "env": {
        "COOLIFY_URL": "http://your-coolify-instance:3000",
        "COOLIFY_API_KEY": "your-api-key"
      }
    }
  }
}

Examples

Deploy a Node.js Application

import { createServer } from 'coolify-mcp'

const server = await createServer()

// List projects
const projects = await server.handleToolCall('list_projects', {})

// Create application
const app = await server.handleToolCall('create_application_public_repo', {
  projectId: 'proj_xxxxxxxx',
  name: 'my-node-app',
  repository: 'owner/my-node-app',
  branch: 'main',
  buildStrategy: 'nixpacks',
  port: 3000
})

// Set environment variables
await server.handleToolCall('bulk_set_envs', {
  applicationId: app.application.id,
  envVars: [
    { key: 'NODE_ENV', value: 'production' },
    { key: 'DATABASE_URL', value: '${DATABASE_URL}', isSecret: true }
  ]
})

// Trigger deployment
const deployment = await server.handleToolCall('trigger_deploy', {
  applicationId: app.application.id
})

Detect Project Type

const detection = await server.handleToolCall('detect_project_type', {
  projectPath: '/path/to/my-project'
})

console.log('Detected:', detection.kind)
console.log('Confidence:', detection.confidence)
console.log('Reasons:', detection.reasons)

Example Payloads

JSON example files matching actual API schemas are in examples/:

File	Description
examples/create-source-app.json	create_application_public_repo payload
examples/create-compose-app.json	create_application_compose payload
examples/set-env-vars.json	bulk_set_envs payload
examples/trigger-deploy.json	trigger_deploy payload
examples/get-application.json	get_application payload
examples/get-logs.json	get_logs payload

All example files are sanitized — no real credentials or endpoint references. Replace all placeholder IDs before use.

Test Fixtures

Realistic project fixtures for testing detection and validation:

File	Description
fixtures/valid-manifest.yaml	Complete valid deploy.intent.yaml
fixtures/invalid-manifest.yaml	Manifest with intentional errors (for validation testing)
fixtures/package.json	Node.js package.json with Express + TypeScript
fixtures/Dockerfile	Multi-stage production Dockerfile
fixtures/docker-compose.yml	Multi-service compose (web, api, worker, db, redis)
fixtures/monorepo-package.json	Monorepo root with pnpm workspaces

Safety & Deployment Risks

Risk	Mitigation
Accidental production deployments	Human approval required before mutations
Secret exposure in logs	API keys never logged; use isSecret: true for sensitive env vars
Rate limiting	Coolify API limited to ~100 req/min; implement backoff in high-volume workflows
Port conflicts	Detection logic warns about common misconfigurations
Resource exhaustion	Set memoryLimit and cpuLimit in deploy.intent.yaml

Documentation Accuracy Note

The official Coolify documentation remains the source of truth for all platform behavior, API endpoints, authentication details, and configuration options.

This repository provides a platform adapter — it wraps Coolify's REST API as MCP tools for use by AI assistants. The docs/coolify-api-mapping.md file documents which endpoints this adapter calls and how. It does not replace the official Coolify API reference.

Limitations

• No support for Coolify's one-click database deployments
• No support for automatic rollback configuration
• No support for Coolify's "remote build" feature
• No webhook subscription for real-time deployment events
• Single Coolify instance (no multi-instance support)
• Requires API key with full project/application permissions

Roadmap

• Add rollback tool
• Add metrics endpoint
• Add cleanup tool
• Add database management tools
• Support for Coolify's one-click databases
• Multi-instance support

Related Repositories

• dokploy-mcp — MCP server for Dokploy
• claude-skill-autodeploy — Claude Code deployment skill
• opencode-skill-autodeploy — OpenCode deployment skill
• codex-skill-autodeploy — Codex deployment skill

License

MIT License — see LICENSE file for details.