Coolify MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Coolify MCP Server list my current applications and their status"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Coolify MCP Server
A robust TypeScript MCP (Model Context Protocol) server for integrating with Coolify, the self-hostable alternative to Netlify and Vercel.
Features
Complete Coolify API Integration: Manage applications, databases, servers, projects, and services
Type-Safe: Full TypeScript support with comprehensive type definitions
MCP Protocol: Compatible with Claude and other MCP clients
Resource Access: Expose Coolify resources through MCP resource endpoints
Tool Support: Comprehensive set of tools for Coolify operations
Related MCP server: Coolify MCP Server
Installation
npm install
npm run buildConfiguration
Environment Variables
The server requires environment variables to connect to your Coolify instance:
export COOLIFY_API_URL="http://localhost:8000"
export COOLIFY_API_TOKEN="your-api-token-here"
export COOLIFY_TEAM_ID="optional-team-id" # OptionalOr create a .env file:
COOLIFY_API_URL=http://localhost:8000
COOLIFY_API_TOKEN=your-api-token-here
COOLIFY_TEAM_ID=optional-team-idMCP Client Configuration
Claude Desktop
Add the server to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"coolify": {
"command": "node",
"args": ["/path/to/coolify-mcp-server/dist/index.js"],
"env": {
"COOLIFY_API_URL": "http://localhost:8000",
"COOLIFY_API_TOKEN": "your-api-token-here",
"COOLIFY_TEAM_ID": "optional-team-id"
}
}
}
}Alternative: NPX Usage
If you publish to npm, users can run via npx:
{
"mcpServers": {
"coolify": {
"command": "npx",
"args": ["@joshuarileydev/coolify-mcp-server", "--yes"],
"env": {
"COOLIFY_API_URL": "http://localhost:8000",
"COOLIFY_API_TOKEN": "your-api-token-here",
"COOLIFY_TEAM_ID": "optional-team-id"
}
}
}
}Or use the executable name directly:
{
"mcpServers": {
"coolify": {
"command": "npx",
"args": ["coolify-mcp-server", "--yes"],
"env": {
"COOLIFY_API_URL": "http://localhost:8000",
"COOLIFY_API_TOKEN": "your-api-token-here",
"COOLIFY_TEAM_ID": "optional-team-id"
}
}
}
}Development Setup
For development, you can use the TypeScript source directly:
{
"mcpServers": {
"coolify": {
"command": "npx",
"args": ["tsx", "/path/to/coolify-mcp-server/src/index.ts"],
"env": {
"COOLIFY_API_URL": "http://localhost:8000",
"COOLIFY_API_TOKEN": "your-api-token-here",
"COOLIFY_TEAM_ID": "optional-team-id"
}
}
}
}Other MCP Clients
For other MCP clients that support environment variables, ensure the following variables are set:
COOLIFY_API_URL(required)COOLIFY_API_TOKEN(required)COOLIFY_TEAM_ID(optional)
Example shell script:
#!/bin/bash
export COOLIFY_API_URL="http://localhost:8000"
export COOLIFY_API_TOKEN="your-api-token-here"
export COOLIFY_TEAM_ID="your-team-id"
node /path/to/coolify-mcp-server/dist/index.jsAvailable Tools
Applications
list_applications- List all applicationsget_application- Get application detailscreate_application- Create new applicationstart_application- Start an applicationstop_application- Stop an applicationrestart_application- Restart an applicationdeploy_application- Deploy an application
Databases
list_databases- List all databasescreate_database- Create new database
Servers
list_servers- List all serverscreate_server- Create new servervalidate_server- Validate server connection
Projects
list_projects- List all projectscreate_project- Create new project
Services
list_services- List all servicesstart_service- Start a servicestop_service- Stop a service
System
get_version- Get Coolify version
Available Resources
The server exposes these MCP resources:
coolify://applications- All applicationscoolify://databases- All databasescoolify://servers- All serverscoolify://projects- All projectscoolify://services- All servicescoolify://teams- All teams
API Token Setup
Log into your Coolify instance
Navigate to "Keys & Tokens" > "API tokens"
Click "Create New Token"
Choose appropriate permissions:
read-only: Read data onlyread:sensitive: Read with sensitive data*: Full access (recommended for MCP server)
Copy the generated token
Security Note
When using the MCP server with Claude Desktop or other clients, your API token will be stored in the configuration file. Ensure this file has appropriate permissions:
# macOS/Linux
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Or set environment variables in your shell profile instead
echo 'export COOLIFY_API_TOKEN="your-token-here"' >> ~/.bashrcDevelopment
# Install dependencies
npm install
# Run in development mode (requires env vars)
COOLIFY_API_URL=http://localhost:8000 COOLIFY_API_TOKEN=your-token npm run dev
# Build for production
npm run build
# Run built version
npm start
# Lint code
npm run lint
# Type check
npm run typecheckTroubleshooting
Common Issues
"COOLIFY_API_URL and COOLIFY_API_TOKEN environment variables are required"
Ensure environment variables are set before starting the server
Check that your
.envfile is in the correct locationVerify variable names are spelled correctly
"Tool execution failed: Request failed"
Verify your Coolify instance is running and accessible
Check that the API URL is correct (include protocol:
http://orhttps://)Ensure your API token has the necessary permissions
MCP server not appearing in Claude Desktop
Restart Claude Desktop after updating configuration
Check the configuration file path is correct for your OS
Verify JSON syntax in the configuration file
Debug Mode
To see detailed error messages, run the server with debug output:
DEBUG=* node dist/index.jsLicense
MIT
Available Tools
18 toolscreate_applicationC
Create a new application
Inputs: name (required), git_branch, description, git_repository.
create_databaseC
Create a new database
Inputs: name (required), type (required).
create_projectB
Create a new project
Inputs: name (required), description.
create_serverC
Create a new server
Inputs: ip (required), name (required), port, user.
deploy_applicationC
Deploy an application
Inputs: id (required), tag.
get_applicationA
Get details of a specific application
Inputs: id (required).
get_versionA
Get Coolify version information
Inputs: no named parameters.
list_applicationsA
List all applications in Coolify
Inputs: no named parameters.
list_databasesA
List all databases in Coolify
Inputs: no named parameters.
list_projectsA
List all projects in Coolify
Inputs: no named parameters.
list_serversA
List all servers in Coolify
Inputs: no named parameters.
list_servicesA
List all services in Coolify
Inputs: no named parameters.
restart_applicationC
Restart an application
Inputs: id (required).
start_applicationC
Start an application
Inputs: id (required).
start_serviceC
Start a service
Inputs: id (required).
stop_applicationC
Stop an application
Inputs: id (required).
stop_serviceC
Stop a service
Inputs: id (required).
validate_serverC
Validate server connection
Inputs: id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Most tools are clearly separated by resource type and action, such as list_applications vs list_databases. The only slight ambiguity is start_application vs deploy_application, which have related but not identical purposes.
All tools use a consistent verb_noun snake_case pattern, e.g., list_applications, create_database, validate_server, get_version. There are no mixed conventions or vague generic names.
18 tools is slightly above the typical sweet spot but reasonable given the server covers applications, databases, servers, projects, services, and version info. Each tool corresponds to a concrete operation, so the count feels justified rather than bloated.
Application lifecycle coverage is fairly strong with create, get, list, start, stop, restart, and deploy, but update and delete are missing. Other resources are much thinner: databases only support list/create, servers list/create/validate, projects list/create, and services list/start/stop, leaving obvious gaps for a management tool.
Related MCP Connectors
Deploy and manage your apps, databases, storage, and scheduled jobs from your AI agent
Deploy apps from GitHub, read build/runtime logs, and manage your app's users from your AI agent.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Manage your own cloud with AI: deploy apps, push and ship custom Docker images, manage resources via your AI agent.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA powerful Model Context Protocol server that enables AI assistants to manage Coolify infrastructure through natural language, supporting application deployment, database management, resource monitoring, and DevOps automation.19MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with Coolify for complete infrastructure management including applications, databases, servers, deployments, and team operations. Provides 100% API coverage with 64 tools for managing the entire Coolify ecosystem through natural language.1811 npm6MIT
- AlicenseBqualityCmaintenanceEnables control and management of Coolify self-hosted PaaS instances, allowing you to deploy applications, manage databases, monitor servers, and execute operations directly from AI assistants.8918 npm28MIT
- AlicenseNot gradedqualityDmaintenanceEnables natural language management of Coolify self-hosted PaaS, including applications, databases, deployments, servers, and environment variables via MCP.MIT