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.

• 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

• Node.js 18+
• A running Coolify instance
• Coolify API token with appropriate permissions
• Docker (for running the MCP server)

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

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

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

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

npm run dev

npm run build
npm start

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

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"
 }
 }
 }
}

• coolify.list_projects - List all projects
• coolify.create_project - Create a new project

• 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

• coolify.deploy_app - Deploy an application
• coolify.get_deployment_status - Check deployment status
• coolify.get_deployment_logs - Get deployment logs

• coolify.deploy_template - Deploy from a pre-configured template
• coolify.list_templates - List available templates

• coolify.check_quota - Check project quota
• coolify.check_name_conflicts - Check if application name is available

// 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://..."
 }
});

// 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 });

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

• 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.

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

All responses follow this structure:

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

Or for errors:

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

• 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

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

# 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

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

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

• 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