Coolify MCP Server

Coolify MCP Server

A Model Context Protocol (MCP) server for Coolify API integration. Control your self-hosted PaaS directly from Claude, Kiro, or any MCP-compatible AI assistant.

Compatible with Coolify v4.0.0-beta.454+ Official npm package for this repository: coolify-mcp-server-kof70

🚀 Features

• Complete API Coverage: Applications, Databases, Servers, Projects, Services, Teams, Deployments, Private Keys
• MCP Resources: Direct resource access via coolify:// URIs
• Version Detection: Automatic feature compatibility based on Coolify version
• Rate Limiting: Built-in rate limit handling with retry logic
• Minimal Dependencies: Only axios and MCP SDK
• TypeScript: Full type safety

📦 Installation

Quick Setup (Recommended)

Run the interactive setup wizard:

npx coolify-mcp-server-kof70 --setup

This will:

1. Ask for your Coolify URL and API token
2. Validate the connection
3. Configure your IDE automatically (Kiro, Cursor, VS Code, Claude Desktop)

Quick Setup with Arguments

npx coolify-mcp-server-kof70 --setup --url https://coolify.example.com --token your-token --ide kiro

Global Installation

npm install -g coolify-mcp-server-kof70
coolify-mcp --setup

From Source

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

⚙️ Configuration

Environment Variables

🔀 Multiple accounts / teams / instances

If you manage several Coolify accounts (different teams, or even different self-hosted instances), you don't need one MCP server config per account. Create ~/.config/coolify-mcp/accounts.json:

{
  "default": "work",
  "accounts": [
    { "name": "work", "baseUrl": "https://coolify.example.com", "token": "1|xxxx" },
    { "name": "client-x", "baseUrl": "https://coolify.client-x.com", "token": "2|yyyy", "teamId": "3" }
  ]
}

Then use these tools from your assistant, no server restart required:

• list_accounts — shows configured accounts (name, base URL, masked token) and which one is active.
• switch_account { name } — switches every subsequent tool call to that account for the rest of the session.
• add_account { name, base_url, token, team_id?, set_default? } — saves a new account to the file (does not switch to it automatically).

If no accounts file exists, the server falls back to the legacy single-account COOLIFY_BASE_URL/COOLIFY_TOKEN environment variables, exposed as an account named env — existing single-account setups keep working unchanged.

🔒 Read-Only Mode

For safe monitoring without risk of accidental changes, enable read-only mode:

{
  "mcpServers": {
    "coolify": {
      "command": "coolify-mcp",
      "env": {
        "COOLIFY_BASE_URL": "https://your-coolify.com",
        "COOLIFY_TOKEN": "your-api-token",
        "COOLIFY_READONLY": "true"
      }
    }
  }
}

In read-only mode, only these operations are available:

• get_* - Get details of resources
• list_* - List resources
• health_check - Check API health

All write operations (create_*, start_*, stop_*, restart_*, deploy_*, execute_command) are disabled.

⚠️ Confirmation for Dangerous Operations

For extra safety, you can require confirmation before executing dangerous operations:

{
  "mcpServers": {
    "coolify": {
      "command": "coolify-mcp",
      "env": {
        "COOLIFY_BASE_URL": "https://your-coolify.com",
        "COOLIFY_TOKEN": "your-api-token",
        "COOLIFY_REQUIRE_CONFIRM": "true"
      }
    }
  }
}

When enabled, these operations require explicit confirmation:

• stop_application, restart_application
• stop_service, restart_service
• deploy_application
• execute_command

Without confirm: true, these operations return a warning:

{
  "confirmation_required": true,
  "action": "stop_application",
  "warning": "This will stop the application and make it unavailable until restarted.",
  "message": "This is a dangerous operation. To proceed, call again with confirm: true",
  "example": { "uuid": "abc123", "confirm": true }
}

To execute, call again with confirm: true:

stop_application({ uuid: "abc123", confirm: true })

Getting an API Token

1. Go to your Coolify instance
2. Navigate to Keys & Tokens → API tokens
3. Create a new token with required permissions:
   • read - For listing resources
   • write - For creating/updating resources
   • deploy - For deployment operations

🔧 Usage

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "coolify": {
      "command": "coolify-mcp",
      "env": {
        "COOLIFY_BASE_URL": "https://your-coolify.com",
        "COOLIFY_TOKEN": "your-api-token"
      }
    }
  }
}

With Kiro

Add to your .kiro/settings/mcp.json:

{
  "mcpServers": {
    "coolify": {
      "command": "coolify-mcp",
      "env": {
        "COOLIFY_BASE_URL": "https://your-coolify.com",
        "COOLIFY_TOKEN": "your-api-token"
      }
    }
  }
}

From Source

{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["/path/to/coolify-mcp-server/build/index.js"],
      "env": {
        "COOLIFY_BASE_URL": "https://your-coolify.com",
        "COOLIFY_TOKEN": "your-api-token"
      }
    }
  }
}

🛠️ Available Tools

Accounts

Version & Health

Teams

Servers

Projects & Environments

Applications

Application Storages

Application Environment Variables

Services

Service Environment Variables

Databases

Deployments

Private Keys

GitHub Apps

Resources

📚 MCP Resources

Access data directly via MCP resources:

coolify://applications    - List all applications
coolify://databases       - List all databases
coolify://servers         - List all servers
coolify://projects        - List all projects
coolify://services        - List all services
coolify://teams           - List all teams
coolify://deployments     - List all deployments
coolify://private-keys    - List all private keys

💡 Example Prompts

Once configured, you can ask your AI assistant:

• "List all my Coolify applications"
• "Deploy the app with UUID abc123"
• "Show me the logs for my-app"
• "Create a new PostgreSQL database called mydb"
• "What servers do I have in Coolify?"
• "Restart the production application"

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

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

🙏 Acknowledgments

• Coolify - The amazing self-hosted PaaS
• Model Context Protocol - The MCP specification
• All contributors who help improve this project

📮 Support

• 🐛 Report a bug
• 💡 Request a feature
• 💬 Discussions