@fndchagas/coolify-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fernando Chagas
+
+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,174 @@
+# coolify-mcp
+
+MCP server for Coolify, pinned to a specific Coolify OpenAPI version.
+
+## Pinned Coolify version
+
+This repo is pinned to:
+
+- `v4.0.0-beta.460`
+- OpenAPI file: `openapi/coolify/v4.0.0-beta.460.json`
+
+## Requirements
+
+- Node 18+
+- A Coolify API token
+
+## Install (package)
+
+```bash
+npm install -g @fndchagas/coolify-mcp
+# or
+npx -y @fndchagas/coolify-mcp
+```
+
+## Use with Claude Code CLI (stdio)
+
+```bash
+claude mcp add coolify \
+  --env COOLIFY_BASE_URL="https://dashboard.coolify.fortetecnologias.com.br" \
+  --env COOLIFY_TOKEN="<token>" \
+  -- npx -y @fndchagas/coolify-mcp
+```
+
+Optional: disable write tools (deploy/upsert) by adding:
+
+```bash
+--env COOLIFY_ALLOW_WRITE=false
+```
+
+## Use with OpenAI Codex CLI (stdio)
+
+```bash
+codex mcp add coolify \
+  --env COOLIFY_BASE_URL="https://dashboard.coolify.fortetecnologias.com.br" \
+  --env COOLIFY_TOKEN="<token>" \
+  -- npx -y @fndchagas/coolify-mcp
+```
+
+Or edit `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.coolify]
+command = "npx"
+args = ["-y", "@fndchagas/coolify-mcp"]
+env = { COOLIFY_BASE_URL = "https://dashboard.coolify.fortetecnologias.com.br", COOLIFY_TOKEN = "<token>" }
+```
+
+## Install (dev)
+
+```bash
+npm install
+```
+
+## Generate types (if OpenAPI changes)
+
+```bash
+npm run generate:openapi
+```
+
+## Run (stdio)
+
+```bash
+COOLIFY_BASE_URL="https://dashboard.coolify.fortetecnologias.com.br" \
+COOLIFY_TOKEN="<token>" \
+MCP_TRANSPORT=stdio \
+npm run dev
+```
+
+## Run (HTTP)
+
+```bash
+COOLIFY_BASE_URL="https://dashboard.coolify.fortetecnologias.com.br" \
+COOLIFY_TOKEN="<token>" \
+MCP_TRANSPORT=http \
+PORT=7331 \
+npm run dev
+```
+
+Endpoint: `POST http://localhost:7331/mcp`
+
+## Run (both)
+
+```bash
+MCP_TRANSPORT=both npm run dev
+```
+
+## Environment variables
+
+- `COOLIFY_BASE_URL` (required)
+- `COOLIFY_TOKEN` (required)
+- `COOLIFY_OPENAPI_REF` (default: `v4.0.0-beta.460`)
+- `COOLIFY_STRICT_VERSION` (default: `false`)
+- `COOLIFY_ALLOW_WRITE` (default: `true`)
+- `MCP_TRANSPORT` (`stdio`, `http`, `both`)
+- `PORT` (HTTP port, default `7331`)
+
+## Tools
+
+- `coolify.listResources`
+- `coolify.getApplication`
+- `coolify.listEnvs`
+- `coolify.upsertEnv`
+- `coolify.deploy`
+- `coolify.getDeployment`
+- `coolify.getLogs`
+- `coolify.listDatabases`
+- `coolify.getDatabase`
+
+## MCP usage examples
+
+### HTTP client (Streamable HTTP)
+
+```ts
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+const client = new Client({ name: 'coolify-client', version: '1.0.0' });
+const transport = new StreamableHTTPClientTransport(
+  new URL('http://localhost:7331/mcp')
+);
+
+await client.connect(transport);
+
+const tools = await client.listTools();
+console.log(tools.tools.map((t) => t.name));
+
+const resources = await client.callTool({
+  name: 'coolify.listResources',
+  arguments: {},
+});
+console.log(resources.structuredContent);
+
+const logs = await client.callTool({
+  name: 'coolify.getLogs',
+  arguments: { appUuid: 'nwggo800g800oosow8ks4c88' },
+});
+console.log(logs.structuredContent);
+
+await client.close();
+```
+
+### Stdio client (spawn server)
+
+```ts
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+// Ensure COOLIFY_BASE_URL and COOLIFY_TOKEN are set in the environment
+const client = new Client({ name: 'coolify-client', version: '1.0.0' });
+const transport = new StdioClientTransport({
+  command: 'node',
+  args: ['dist/server.js'],
+});
+
+await client.connect(transport);
+
+const result = await client.callTool({
+  name: 'coolify.getApplication',
+  arguments: { uuid: 'nwggo800g800oosow8ks4c88' },
+});
+console.log(result.structuredContent);
+
+await client.close();
+```

package/dist/config.js

@@ -0,0 +1,7 @@
+export const COOLIFY_BASE_URL = process.env.COOLIFY_BASE_URL;
+export const COOLIFY_TOKEN = process.env.COOLIFY_TOKEN;
+export const COOLIFY_OPENAPI_REF = process.env.COOLIFY_OPENAPI_REF ?? 'v4.0.0-beta.460';
+export const MCP_TRANSPORT = process.env.MCP_TRANSPORT ?? 'stdio';
+export const MCP_HTTP_PORT = Number(process.env.PORT ?? '7331');
+export const COOLIFY_STRICT_VERSION = process.env.COOLIFY_STRICT_VERSION === 'true';
+export const COOLIFY_ALLOW_WRITE = process.env.COOLIFY_ALLOW_WRITE !== 'false';

package/dist/coolify/client.js

@@ -0,0 +1,53 @@
+import { COOLIFY_BASE_URL, COOLIFY_TOKEN } from '../config.js';
+function requireEnv(value, name) {
+    if (!value) {
+        throw new Error(`${name} is required`);
+    }
+    return value;
+}
+function buildUrl(path, query) {
+    const base = requireEnv(COOLIFY_BASE_URL, 'COOLIFY_BASE_URL');
+    const url = new URL(path, base);
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined) {
+                url.searchParams.set(key, value);
+            }
+        }
+    }
+    return url.toString();
+}
+export async function request(method, path, options) {
+    const token = requireEnv(COOLIFY_TOKEN, 'COOLIFY_TOKEN');
+    const url = buildUrl(path, options?.query);
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json',
+    };
+    let body;
+    if (options?.body !== undefined) {
+        headers['Content-Type'] = 'application/json';
+        body = JSON.stringify(options.body);
+    }
+    const response = await fetch(url, { method, headers, body });
+    const contentType = response.headers.get('content-type') ?? '';
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Coolify API error ${response.status}: ${text || response.statusText}`);
+    }
+    if (contentType.includes('application/json')) {
+        return (await response.json());
+    }
+    return (await response.text());
+}
+export async function getVersion() {
+    const data = await request('GET', '/api/v1/version');
+    if (typeof data === 'string') {
+        return data.trim();
+    }
+    if (data && typeof data === 'object' && 'version' in data) {
+        const version = data.version;
+        return version ?? 'unknown';
+    }
+    return 'unknown';
+}

package/dist/generated/coolify-api.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/dist/server.js

@@ -0,0 +1,66 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import express from 'express';
+import { registerCoolifyTools } from './tools/coolify.js';
+import { COOLIFY_OPENAPI_REF, COOLIFY_STRICT_VERSION, MCP_HTTP_PORT, MCP_TRANSPORT, } from './config.js';
+import { getVersion } from './coolify/client.js';
+const server = new McpServer({
+    name: 'coolify-mcp',
+    version: '0.1.0',
+});
+registerCoolifyTools(server);
+function normalizeVersion(value) {
+    return value.replace(/^v/i, '');
+}
+async function checkVersion() {
+    try {
+        const current = await getVersion();
+        if (normalizeVersion(current) !== normalizeVersion(COOLIFY_OPENAPI_REF)) {
+            const message = `Coolify version mismatch. Server=${current}, OpenAPI=${COOLIFY_OPENAPI_REF}.`;
+            if (COOLIFY_STRICT_VERSION) {
+                throw new Error(message);
+            }
+            console.warn(message);
+        }
+    }
+    catch (error) {
+        if (COOLIFY_STRICT_VERSION) {
+            throw error;
+        }
+        console.warn('Version check failed:', error instanceof Error ? error.message : error);
+    }
+}
+async function startStdio() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+async function startHttp() {
+    const app = express();
+    app.use(express.json());
+    app.post('/mcp', async (req, res) => {
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+        });
+        res.on('close', () => transport.close());
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    });
+    app.listen(MCP_HTTP_PORT, () => {
+        console.log(`MCP HTTP server listening on :${MCP_HTTP_PORT}/mcp`);
+    });
+}
+await checkVersion();
+if (MCP_TRANSPORT === 'stdio') {
+    await startStdio();
+}
+else if (MCP_TRANSPORT === 'http') {
+    await startHttp();
+}
+else if (MCP_TRANSPORT === 'both') {
+    await Promise.all([startStdio(), startHttp()]);
+}
+else {
+    throw new Error(`Unknown MCP_TRANSPORT: ${MCP_TRANSPORT}`);
+}

package/dist/tools/coolify.js

@@ -0,0 +1,130 @@
+import * as z from 'zod';
+import { request } from '../coolify/client.js';
+import { COOLIFY_ALLOW_WRITE } from '../config.js';
+function ensureWriteAllowed() {
+    if (!COOLIFY_ALLOW_WRITE) {
+        throw new Error('Write operations are disabled (COOLIFY_ALLOW_WRITE=false).');
+    }
+}
+export function registerCoolifyTools(server) {
+    server.registerTool('coolify.listResources', {
+        title: 'List resources',
+        description: 'List Coolify resources (apps, databases, etc).',
+        inputSchema: {},
+        outputSchema: { resources: z.array(z.unknown()) },
+    }, async () => {
+        const data = await request('GET', '/api/v1/resources');
+        return {
+            content: [{ type: 'text', text: 'Resources fetched.' }],
+            structuredContent: { resources: data },
+        };
+    });
+    server.registerTool('coolify.getApplication', {
+        title: 'Get application',
+        description: 'Get application details by UUID.',
+        inputSchema: { uuid: z.string() },
+        outputSchema: { application: z.unknown() },
+    }, async ({ uuid }) => {
+        const data = await request('GET', `/api/v1/applications/${uuid}`);
+        return {
+            content: [{ type: 'text', text: `Application ${uuid} fetched.` }],
+            structuredContent: { application: data },
+        };
+    });
+    server.registerTool('coolify.listEnvs', {
+        title: 'List application env vars',
+        description: 'List environment variables for an application.',
+        inputSchema: { appUuid: z.string() },
+        outputSchema: { envs: z.array(z.unknown()) },
+    }, async ({ appUuid }) => {
+        const data = await request('GET', `/api/v1/applications/${appUuid}/envs`);
+        return {
+            content: [{ type: 'text', text: `Env vars for ${appUuid} fetched.` }],
+            structuredContent: { envs: data },
+        };
+    });
+    server.registerTool('coolify.upsertEnv', {
+        title: 'Upsert environment variable',
+        description: 'Upsert an environment variable for an application.',
+        inputSchema: {
+            appUuid: z.string(),
+            key: z.string(),
+            value: z.string(),
+            is_buildtime: z.boolean().optional(),
+            is_runtime: z.boolean().optional(),
+        },
+        outputSchema: { env: z.unknown() },
+    }, async ({ appUuid, key, value, is_buildtime = true, is_runtime = true }) => {
+        ensureWriteAllowed();
+        const data = await request('PATCH', `/api/v1/applications/${appUuid}/envs`, {
+            body: { key, value, is_buildtime, is_runtime },
+        });
+        return {
+            content: [{ type: 'text', text: `Env ${key} upserted for ${appUuid}.` }],
+            structuredContent: { env: data },
+        };
+    });
+    server.registerTool('coolify.deploy', {
+        title: 'Trigger deploy',
+        description: 'Trigger a deployment for an application.',
+        inputSchema: { appUuid: z.string(), force: z.boolean().optional() },
+        outputSchema: { deployment: z.unknown() },
+    }, async ({ appUuid, force = true }) => {
+        ensureWriteAllowed();
+        const data = await request('POST', '/api/v1/deploy', {
+            query: { uuid: appUuid, force: String(force) },
+        });
+        return {
+            content: [{ type: 'text', text: `Deploy triggered for ${appUuid}.` }],
+            structuredContent: { deployment: data },
+        };
+    });
+    server.registerTool('coolify.getDeployment', {
+        title: 'Get deployment',
+        description: 'Get deployment status by UUID.',
+        inputSchema: { deploymentUuid: z.string() },
+        outputSchema: { deployment: z.unknown() },
+    }, async ({ deploymentUuid }) => {
+        const data = await request('GET', `/api/v1/deployments/${deploymentUuid}`);
+        return {
+            content: [{ type: 'text', text: `Deployment ${deploymentUuid} fetched.` }],
+            structuredContent: { deployment: data },
+        };
+    });
+    server.registerTool('coolify.getLogs', {
+        title: 'Get application logs',
+        description: 'Fetch runtime logs for an application.',
+        inputSchema: { appUuid: z.string() },
+        outputSchema: { logs: z.string() },
+    }, async ({ appUuid }) => {
+        const data = await request('GET', `/api/v1/applications/${appUuid}/logs`);
+        return {
+            content: [{ type: 'text', text: 'Logs fetched.' }],
+            structuredContent: { logs: data.logs ?? '' },
+        };
+    });
+    server.registerTool('coolify.listDatabases', {
+        title: 'List databases',
+        description: 'List Coolify databases.',
+        inputSchema: {},
+        outputSchema: { databases: z.array(z.unknown()) },
+    }, async () => {
+        const data = await request('GET', '/api/v1/databases');
+        return {
+            content: [{ type: 'text', text: 'Databases fetched.' }],
+            structuredContent: { databases: data },
+        };
+    });
+    server.registerTool('coolify.getDatabase', {
+        title: 'Get database',
+        description: 'Get database details by UUID.',
+        inputSchema: { uuid: z.string() },
+        outputSchema: { database: z.unknown() },
+    }, async ({ uuid }) => {
+        const data = await request('GET', `/api/v1/databases/${uuid}`);
+        return {
+            content: [{ type: 'text', text: `Database ${uuid} fetched.` }],
+            structuredContent: { database: data },
+        };
+    });
+}