Coolify MCP Server

A Model Context Protocol (MCP) server that exposes Coolify API functionality as safe, structured tools for AI agents. This enables AI-driven app marketplaces where users can deploy applications on Coolify with a single click.

🚀 Features

• Project Management: List, create, and manage Coolify projects

• Application Lifecycle: Create, update, delete, and manage applications

• Deployment Control: Deploy applications and monitor their status

• Template Marketplace: Pre-configured templates for popular applications

• Safety Guardrails: Quota checking, name conflict detection, and resource limits

• Comprehensive Logging: Full audit trail of all AI operations

📋 Prerequisites

• Node.js 18+

• A running Coolify instance

• Coolify API token with appropriate permissions

• Docker (for running the MCP server)

🛠️ Installation

Option 1: Clone and Build

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

Option 2: Docker (Recommended)

docker pull ghcr.io/your-org/coolify-mcp-server:latest

⚙️ Configuration

Create a .env file based on .env.example:

# Required
COOLIFY_API_URL=https://your-coolify-instance.com
COOLIFY_API_TOKEN=your-api-token-here

# Optional
COOLIFY_DEFAULT_TEAM_ID=
COOLIFY_MAX_APPS_PER_PROJECT=10
LOG_LEVEL=info

Getting Your Coolify API Token

1. Log into your Coolify instance

2. Go to Settings → API Tokens

3. Create a new token with permissions for:

   • Projects: Read/Write

   • Applications: Read/Write/Delete

   • Deployments: Read/Write

🏃 Running the Server

Development

npm run dev

Production

npm run build
npm start

Docker

docker run \
  -e COOLIFY_API_URL=https://coolify.example.com \
  -e COOLIFY_API_TOKEN=your-token \
  -e COOLIFY_MAX_APPS_PER_PROJECT=20 \
  ghcr.io/your-org/coolify-mcp-server:latest

🔧 MCP Client Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["/path/to/coolify-mcp-server/dist/index.js"],
      "env": {
        "COOLIFY_API_URL": "https://your-coolify-instance.com",
        "COOLIFY_API_TOKEN": "your-api-token",
        "COOLIFY_MAX_APPS_PER_PROJECT": "10"
      }
    }
  }
}

📚 Available Tools

Projects

• coolify.list_projects - List all projects

• coolify.create_project - Create a new project

Applications

• coolify.list_apps - List applications in a project

• coolify.get_app - Get application details

• coolify.create_app - Create a new application

• coolify.update_app - Update an application

• coolify.delete_app - Delete an application

Deployments

• coolify.deploy_app - Deploy an application

• coolify.get_deployment_status - Check deployment status

• coolify.get_deployment_logs - Get deployment logs

Templates

• coolify.deploy_template - Deploy from a pre-configured template

• coolify.list_templates - List available templates

Safety

• coolify.check_quota - Check project quota

• coolify.check_name_conflicts - Check if application name is available

🎯 Quick Start Examples

Deploy Plausible Analytics

// First, check if the name is available
await checkNameConflicts({
  projectId: "proj-123",
  name: "plausible-analytics"
});

// Deploy the template
const result = await deployTemplate({
  templateName: "plausible",
  projectId: "proj-123",
  appName: "plausible-analytics",
  environment: {
    BASE_URL: "https://analytics.example.com",
    SECRET_KEY_BASE: "your-secret-key",
    POSTGRES_URL: "postgresql://..."
  }
});

Deploy Custom Application

// Create a new application
const app = await createApp({
  projectId: "proj-123",
  name: "my-react-app",
  type: "dockerfile",
  gitRepository: {
    url: "https://github.com/user/react-app.git",
    branch: "main"
  },
  environment: {
    NODE_ENV: "production"
  },
  ports: [3000]
});

// Deploy it
const deployment = await deployApp({ id: app.id });

📦 Available Templates

See examples/tool-calls.md for detailed examples.

🔒 Security

• API tokens are stored server-side and never exposed to AI agents

• All inputs are validated with strict schemas

• Project-level isolation prevents cross-project access

• Built-in quota and rate limiting

• Comprehensive audit logging

See docs/SECURITY.md for detailed security considerations.

📝 API Reference

The MCP server exposes the following endpoints through the Model Context Protocol:

Response Format

All responses follow this structure:

{
  "success": true,
  "data": { ... }
}

Or for errors:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}

Error Codes

• UNAUTHORIZED - Invalid API token

• FORBIDDEN - Insufficient permissions

• NOT_FOUND - Resource doesn't exist

• CONFLICT - Resource conflict (e.g., duplicate name)

• VALIDATION_ERROR - Invalid input data

• RATE_LIMIT - Too many requests

• QUOTA_EXCEEDED - Project quota exceeded

• NETWORK_ERROR - Failed to connect to Coolify

• UNKNOWN_ERROR - Unexpected error

🤝 Contributing

1. Fork the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Commit your changes: git commit -m 'Add amazing feature'

4. Push to the branch: git push origin feature/amazing-feature

5. Open a Pull Request

Development Setup

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 📖 Documentation

• 🐛 Issue Tracker

• 💬 Discussions

🙏 Acknowledgments

• Coolify - The amazing self-hosting platform

• Model Context Protocol - The protocol that makes this possible

• All contributors and users of this project

Built with ❤️ by the community