@softtor/coolify-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Softtor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# Coolify MCP Server
+
+[![npm version](https://badge.fury.io/js/@softtor%2Fcoolify-mcp-server.svg)](https://www.npmjs.com/package/@softtor/coolify-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+MCP (Model Context Protocol) server for [Coolify](https://coolify.io) API integration. Manage your applications, databases, services, servers, and deployments directly from Claude Code or any MCP-compatible client.
+
+## Features
+
+- Multi-team support with dynamic API key configuration
+- 27 tools covering all major Coolify operations
+- Full TypeScript support
+- Compatible with Claude Code and other MCP clients
+
+## Installation
+
+### Using npx (Recommended)
+
+No installation required. Configure directly in your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "coolify": {
+      "command": "npx",
+      "args": ["-y", "@softtor/coolify-mcp-server"],
+      "env": {
+        "COOLIFY_BASE_URL": "https://your-coolify-instance.com",
+        "COOLIFY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Global Installation
+
+```bash
+npm install -g @softtor/coolify-mcp-server
+```
+
+Then configure in your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "coolify": {
+      "command": "coolify-mcp-server",
+      "env": {
+        "COOLIFY_BASE_URL": "https://your-coolify-instance.com",
+        "COOLIFY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `COOLIFY_BASE_URL` | No | Coolify instance URL (default: `https://cloud.softtor.com.br`) |
+| `COOLIFY_API_KEY` | No* | Default API key |
+| `COOLIFY_DEFAULT_TEAM` | No | Default team name (default: `default`) |
+| `COOLIFY_TEAM_<NAME>_API_KEY` | No* | Team-specific API key |
+
+*At least one API key must be provided.
+
+### Multi-Team Configuration
+
+For organizations with multiple Coolify teams, configure team-specific API keys:
+
+```json
+{
+  "mcpServers": {
+    "coolify": {
+      "command": "npx",
+      "args": ["-y", "@softtor/coolify-mcp-server"],
+      "env": {
+        "COOLIFY_BASE_URL": "https://your-coolify-instance.com",
+        "COOLIFY_DEFAULT_TEAM": "production",
+        "COOLIFY_TEAM_PRODUCTION_API_KEY": "prod-api-key",
+        "COOLIFY_TEAM_STAGING_API_KEY": "staging-api-key",
+        "COOLIFY_TEAM_DEV_API_KEY": "dev-api-key"
+      }
+    }
+  }
+}
+```
+
+Then use the `team` parameter in any tool:
+
+```
+coolify_list_applications { team: "staging" }
+```
+
+### Getting Your API Key
+
+1. Log in to your Coolify instance
+2. Go to **Settings** > **API Tokens**
+3. Create a new token with appropriate permissions
+4. Copy the token and use it as your API key
+
+## Available Tools
+
+### Applications (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coolify_list_applications` | List all applications |
+| `coolify_get_application` | Get application details by UUID |
+| `coolify_start_application` | Start/deploy an application |
+| `coolify_stop_application` | Stop a running application |
+| `coolify_restart_application` | Restart an application |
+| `coolify_get_application_logs` | Get container logs |
+
+### Databases (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coolify_list_databases` | List all databases |
+| `coolify_get_database` | Get database details by UUID |
+| `coolify_start_database` | Start a database |
+| `coolify_stop_database` | Stop a running database |
+| `coolify_restart_database` | Restart a database |
+| `coolify_list_database_backups` | List database backups |
+
+### Services (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coolify_list_services` | List all services |
+| `coolify_get_service` | Get service details by UUID |
+| `coolify_start_service` | Start a service |
+| `coolify_stop_service` | Stop a running service |
+| `coolify_restart_service` | Restart a service |
+
+### Servers (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coolify_list_servers` | List all servers |
+| `coolify_get_server` | Get server details by UUID |
+| `coolify_get_server_resources` | Get all resources on a server |
+| `coolify_get_server_domains` | Get all domains mapped on a server |
+
+### Deployments (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coolify_deploy` | Deploy by UUID or tag |
+| `coolify_list_deployments` | List deployment history |
+
+### Projects & Teams (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `coolify_list_projects` | List all projects |
+| `coolify_get_project` | Get project details by UUID |
+| `coolify_list_teams` | List all accessible teams |
+| `coolify_get_team` | Get team details by ID |
+
+## Usage Examples
+
+### List all applications
+
+```
+coolify_list_applications
+```
+
+### Deploy an application
+
+```
+coolify_deploy { uuid: "app-uuid-here" }
+```
+
+### Deploy with force rebuild
+
+```
+coolify_deploy { uuid: "app-uuid-here", force: true }
+```
+
+### Deploy all applications with a tag
+
+```
+coolify_deploy { tag: "production" }
+```
+
+### Get application logs
+
+```
+coolify_get_application_logs { uuid: "app-uuid-here", since: 3600 }
+```
+
+### Use a specific team
+
+```
+coolify_list_applications { team: "staging" }
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/Softtor/coolify-mcp-server.git
+cd coolify-mcp-server
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run locally
+COOLIFY_API_KEY=your-key npm start
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Related
+
+- [Coolify](https://coolify.io) - Self-hostable Heroku/Netlify alternative
+- [Model Context Protocol](https://modelcontextprotocol.io) - Protocol for AI tool integration
+- [Claude Code](https://claude.ai/code) - Anthropic's CLI for Claude

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+export interface TeamConfig {
+    name: string;
+    apiKey: string;
+}
+export interface Config {
+    baseUrl: string;
+    defaultTeam: string;
+    teams: Map<string, TeamConfig>;
+}
+export declare function getConfig(): Config;
+export declare function getTeamApiKey(teamName?: string): string;
+export declare function listAvailableTeams(): string[];

package/dist/config.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+const ConfigSchema = z.object({
+    baseUrl: z.string().url(),
+    defaultTeam: z.string().min(1),
+});
+function loadTeams() {
+    const teams = new Map();
+    for (const [key, value] of Object.entries(process.env)) {
+        const match = key.match(/^COOLIFY_TEAM_(.+)_API_KEY$/);
+        if (match && value) {
+            const teamName = match[1].toLowerCase();
+            teams.set(teamName, { name: teamName, apiKey: value });
+        }
+    }
+    if (process.env.COOLIFY_API_KEY) {
+        teams.set("default", { name: "default", apiKey: process.env.COOLIFY_API_KEY });
+    }
+    return teams;
+}
+let configInstance = null;
+export function getConfig() {
+    if (configInstance) {
+        return configInstance;
+    }
+    const teams = loadTeams();
+    if (teams.size === 0) {
+        throw new Error("No API keys configured. Set COOLIFY_API_KEY or COOLIFY_TEAM_<NAME>_API_KEY environment variables.");
+    }
+    const baseUrl = process.env.COOLIFY_BASE_URL || "https://cloud.softtor.com.br";
+    const envDefaultTeam = process.env.COOLIFY_DEFAULT_TEAM || "default";
+    const defaultTeam = teams.has(envDefaultTeam) ? envDefaultTeam : teams.keys().next().value;
+    const validatedConfig = ConfigSchema.parse({
+        baseUrl,
+        defaultTeam,
+    });
+    configInstance = {
+        ...validatedConfig,
+        teams,
+    };
+    return configInstance;
+}
+export function getTeamApiKey(teamName) {
+    const config = getConfig();
+    const team = teamName || config.defaultTeam;
+    const teamConfig = config.teams.get(team.toLowerCase());
+    if (!teamConfig) {
+        const availableTeams = Array.from(config.teams.keys()).join(", ");
+        throw new Error(`Team "${team}" not found. Available teams: ${availableTeams}`);
+    }
+    return teamConfig.apiKey;
+}
+export function listAvailableTeams() {
+    const config = getConfig();
+    return Array.from(config.teams.keys());
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { getConfig, listAvailableTeams } from "./config.js";
+import { applicationTools } from "./tools/applications.js";
+import { databaseTools } from "./tools/databases.js";
+import { serviceTools } from "./tools/services.js";
+import { serverTools } from "./tools/servers.js";
+import { deploymentTools } from "./tools/deployments.js";
+import { projectTools } from "./tools/projects.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const allTools = [
+    ...applicationTools,
+    ...databaseTools,
+    ...serviceTools,
+    ...serverTools,
+    ...deploymentTools,
+    ...projectTools,
+];
+function zodToJsonSchema(schema) {
+    if (schema instanceof z.ZodObject) {
+        const shape = schema.shape;
+        const properties = {};
+        const required = [];
+        for (const [key, value] of Object.entries(shape)) {
+            const zodValue = value;
+            properties[key] = zodFieldToJsonSchema(zodValue);
+            if (!(zodValue instanceof z.ZodOptional)) {
+                required.push(key);
+            }
+        }
+        return {
+            type: "object",
+            properties,
+            required: required.length > 0 ? required : undefined,
+        };
+    }
+    if (schema instanceof z.ZodEffects) {
+        return zodToJsonSchema(schema._def.schema);
+    }
+    return { type: "object" };
+}
+function zodFieldToJsonSchema(field) {
+    if (field instanceof z.ZodString) {
+        return {
+            type: "string",
+            description: field.description,
+        };
+    }
+    if (field instanceof z.ZodNumber) {
+        return {
+            type: "number",
+            description: field.description,
+        };
+    }
+    if (field instanceof z.ZodBoolean) {
+        return {
+            type: "boolean",
+            description: field.description,
+        };
+    }
+    if (field instanceof z.ZodOptional) {
+        return zodFieldToJsonSchema(field._def.innerType);
+    }
+    if (field instanceof z.ZodDefault) {
+        return zodFieldToJsonSchema(field._def.innerType);
+    }
+    return { type: "string" };
+}
+const server = new Server({
+    name: "coolify-mcp-server",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const config = getConfig();
+    const teams = listAvailableTeams();
+    const teamsInfo = `Available teams: ${teams.join(", ")}. Default: ${config.defaultTeam}`;
+    return {
+        tools: allTools.map((tool) => ({
+            name: tool.name,
+            description: `${tool.description}\n\n${teamsInfo}`,
+            inputSchema: zodToJsonSchema(tool.inputSchema),
+        })),
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const tool = allTools.find((t) => t.name === name);
+    if (!tool) {
+        throw new Error(`Unknown tool: ${name}`);
+    }
+    try {
+        const validatedArgs = tool.inputSchema.parse(args);
+        const result = await tool.handler(validatedArgs);
+        return {
+            content: [{ type: "text", text: result }],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${errorMessage}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    try {
+        getConfig();
+    }
+    catch (error) {
+        console.error("Configuration error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/schemas/common.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+export declare const TeamParamSchema: z.ZodObject<{
+    team: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    team?: string | undefined;
+}, {
+    team?: string | undefined;
+}>;
+export declare const UuidParamSchema: z.ZodObject<{
+    team: z.ZodOptional<z.ZodString>;
+} & {
+    uuid: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    uuid: string;
+    team?: string | undefined;
+}, {
+    uuid: string;
+    team?: string | undefined;
+}>;
+export declare const DeployParamSchema: z.ZodObject<{
+    team: z.ZodOptional<z.ZodString>;
+} & {
+    uuid: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+    force: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    team?: string | undefined;
+    uuid?: string | undefined;
+    tag?: string | undefined;
+    force?: boolean | undefined;
+}, {
+    team?: string | undefined;
+    uuid?: string | undefined;
+    tag?: string | undefined;
+    force?: boolean | undefined;
+}>;
+export declare const LogsParamSchema: z.ZodObject<{
+    team: z.ZodOptional<z.ZodString>;
+} & {
+    uuid: z.ZodString;
+} & {
+    since: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    uuid: string;
+    team?: string | undefined;
+    since?: number | undefined;
+}, {
+    uuid: string;
+    team?: string | undefined;
+    since?: number | undefined;
+}>;

package/dist/schemas/common.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export const TeamParamSchema = z.object({
+    team: z.string().optional().describe("Team name to use (default: configured default team)"),
+});
+export const UuidParamSchema = TeamParamSchema.extend({
+    uuid: z.string().describe("Resource UUID"),
+});
+export const DeployParamSchema = TeamParamSchema.extend({
+    uuid: z.string().optional().describe("Application UUID to deploy"),
+    tag: z.string().optional().describe("Tag to deploy (deploys all resources with this tag)"),
+    force: z.boolean().optional().describe("Force rebuild without cache"),
+});
+export const LogsParamSchema = UuidParamSchema.extend({
+    since: z.number().optional().describe("Get logs since N seconds ago (default: 3600)"),
+});

package/dist/services/coolify-client.d.ts

@@ -0,0 +1,12 @@
+type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
+export interface RequestOptions {
+    team?: string;
+    timeout?: number;
+    params?: Record<string, string | number | boolean | undefined>;
+}
+export declare function coolifyRequest<T>(endpoint: string, method?: HttpMethod, data?: unknown, options?: RequestOptions): Promise<T>;
+export declare function coolifyGet<T>(endpoint: string, options?: RequestOptions): Promise<T>;
+export declare function coolifyPost<T>(endpoint: string, data?: unknown, options?: RequestOptions): Promise<T>;
+export declare function coolifyPatch<T>(endpoint: string, data?: unknown, options?: RequestOptions): Promise<T>;
+export declare function coolifyDelete<T>(endpoint: string, options?: RequestOptions): Promise<T>;
+export {};

package/dist/services/coolify-client.js

@@ -0,0 +1,48 @@
+import axios from "axios";
+import { getConfig, getTeamApiKey } from "../config.js";
+import { handleApiError, formatErrorResponse } from "./error-handler.js";
+export async function coolifyRequest(endpoint, method = "GET", data, options = {}) {
+    const config = getConfig();
+    const apiKey = getTeamApiKey(options.team);
+    const axiosConfig = {
+        method,
+        url: `${config.baseUrl}/api/v1${endpoint}`,
+        timeout: options.timeout ?? 30000,
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+        },
+    };
+    if (data) {
+        axiosConfig.data = data;
+    }
+    if (options.params) {
+        const filteredParams = {};
+        for (const [key, value] of Object.entries(options.params)) {
+            if (value !== undefined) {
+                filteredParams[key] = value;
+            }
+        }
+        axiosConfig.params = filteredParams;
+    }
+    try {
+        const response = await axios(axiosConfig);
+        return response.data;
+    }
+    catch (error) {
+        const apiError = handleApiError(error);
+        throw new Error(formatErrorResponse(apiError));
+    }
+}
+export async function coolifyGet(endpoint, options = {}) {
+    return coolifyRequest(endpoint, "GET", undefined, options);
+}
+export async function coolifyPost(endpoint, data, options = {}) {
+    return coolifyRequest(endpoint, "POST", data, options);
+}
+export async function coolifyPatch(endpoint, data, options = {}) {
+    return coolifyRequest(endpoint, "PATCH", data, options);
+}
+export async function coolifyDelete(endpoint, options = {}) {
+    return coolifyRequest(endpoint, "DELETE", undefined, options);
+}

package/dist/services/error-handler.d.ts

@@ -0,0 +1,7 @@
+export interface CoolifyError {
+    message: string;
+    status?: number;
+    details?: unknown;
+}
+export declare function handleApiError(error: unknown): CoolifyError;
+export declare function formatErrorResponse(error: CoolifyError): string;

package/dist/services/error-handler.js

@@ -0,0 +1,59 @@
+import { AxiosError } from "axios";
+export function handleApiError(error) {
+    if (error instanceof AxiosError) {
+        const status = error.response?.status;
+        const data = error.response?.data;
+        if (status === 401) {
+            return {
+                message: "Authentication failed. Check your API key.",
+                status,
+                details: data,
+            };
+        }
+        if (status === 403) {
+            return {
+                message: "Access denied. Your API key may not have permission for this operation.",
+                status,
+                details: data,
+            };
+        }
+        if (status === 404) {
+            return {
+                message: "Resource not found.",
+                status,
+                details: data,
+            };
+        }
+        if (status === 422) {
+            return {
+                message: "Validation error.",
+                status,
+                details: data,
+            };
+        }
+        return {
+            message: data?.message || error.message || "Unknown API error",
+            status,
+            details: data,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            message: error.message,
+        };
+    }
+    return {
+        message: "Unknown error occurred",
+        details: error,
+    };
+}
+export function formatErrorResponse(error) {
+    let response = `Error: ${error.message}`;
+    if (error.status) {
+        response += ` (HTTP ${error.status})`;
+    }
+    if (error.details) {
+        response += `\nDetails: ${JSON.stringify(error.details, null, 2)}`;
+    }
+    return response;
+}