Content
# 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
```bash
git clone https://github.com/REPLACE_WITH_ORG/coolify-mcp
cd coolify-mcp
npm install
npm run build
```
## Configuration
### Environment Variables
```bash
export COOLIFY_URL="http://your-coolify-instance:3000"
export COOLIFY_API_KEY="your-api-key"
```
### Claude Code Setup
Add to `~/.claude/settings.json`:
```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
```typescript
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
```typescript
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](https://coolify.io/docs) 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
<!-- Update these URLs before publishing. Replace REPLACE_WITH_ORG with your GitHub organization. -->
- [dokploy-mcp](https://github.com/REPLACE_WITH_ORG/dokploy-mcp) — MCP server for Dokploy
- [claude-skill-autodeploy](https://github.com/REPLACE_WITH_ORG/claude-skill-autodeploy) — Claude Code deployment skill
- [opencode-skill-autodeploy](https://github.com/REPLACE_WITH_ORG/opencode-skill-autodeploy) — OpenCode deployment skill
- [codex-skill-autodeploy](https://github.com/REPLACE_WITH_ORG/codex-skill-autodeploy) — Codex deployment skill
## License
MIT License — see [LICENSE](LICENSE) file for details.
