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

Template	Description	Type	Services
plausible	Privacy-friendly analytics	Docker Image	PostgreSQL
strapi	Headless CMS	Git	PostgreSQL, MySQL
saleor	E-commerce platform	Docker Image	PostgreSQL, Redis
n8n	Workflow automation	Docker Image	PostgreSQL, Redis
uptime-kuma	Monitoring tool	Docker Image	-
gitlab	Git repository manager	Docker Image	PostgreSQL, Redis
rocketchat	Communication platform	Docker Image	MongoDB
bookstack	Documentation platform	Docker Image	MySQL, PostgreSQL

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