Coolify MCP

Manage your Coolify infrastructure from your AI agent.

A local Model Context Protocol (MCP) server for developers running applications on Coolify. Give your agent access to application status, deployment logs, environment variables, databases, and more through three tools: guide, search, and execute.

Code Mode lets the agent compose multiple Coolify API calls in one JavaScript function and return the fields you need. Intermediate responses stay inside the function unless the code returns or logs them.

Quick start · Example workflow · Tool reference · Operation coverage

Put it to work

Once connected, try prompts like these:

| Task | Prompt | | --- | --- | | Check application status | “List my Coolify applications with their names, UUIDs, and statuses. Do not make any changes.” | | Investigate a deployment | “Inspect the latest deployment and recent logs for application <uuid>. Summarize the errors without changing anything.” | | Inspect configuration | “List the environment variable names for application <uuid>. Do not return secret values or make changes.” | | Plan a deployment | “Show a dry-run request plan to deploy application <uuid>. Do not send the deployment request.” |

These are example instructions for your agent. Read the safety model before using workflows that change resources.

Why Code Mode?

Discover the operation you need, combine related calls, and choose what comes back to the conversation.

| Tool | What it does | | --- | --- | | guide | Provides Coolify workflow guidance for discovery, deployments, logs, environment variables, lifecycle actions, deletion, backups, and formatting. | | search | Inspects the embedded OpenAPI spec to find operation IDs, parameters, request bodies, and risk classifications. No Coolify credentials required. | | execute | Runs one or more authenticated API calls and returns your selected results. Supports request previews with dryRun. |

The bundled Coolify v4.x OpenAPI snapshot covers 136 operations, including applications, projects, servers, services, databases, deployments, and backups. See the full operation catalog for coverage and classifications. Coverage reflects the bundled snapshot; your Coolify instance may expose newer endpoints.

Quick start

You need Node.js 22 or newer, npm, an existing Coolify instance with an API token, and an MCP client that can launch local stdio servers.

1. Connect your MCP client

Once the first npm release is published, clients that use an mcpServers configuration can launch the package with npx:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["-y", "@j0nl1/[email protected]"],
      "env": {
        "COOLIFY_BASE_URL": "https://coolify.example.com",
        "COOLIFY_API_TOKEN": "your-coolify-api-token"
      }
    }
  }
}

Set your instance URL and token. If your client uses another configuration format, enter the same command, arguments, and environment variables in its local MCP server settings. The npm package runs on Node.js across platforms and does not require Bun.

Alternatively, install it globally with npm install -g @j0nl1/[email protected] and use coolify-mcp as the command with no arguments.

COOLIFY_BASE_URL accepts either the instance origin (https://coolify.example.com) or the API root (https://coolify.example.com/api/v1). Keep the token in your local client configuration and out of version control.

Reload your client's MCP configuration. It should expose guide, search, and execute; the server communicates over stdio and is launched by the client.

2. Make a read-only first request

Ask your agent:

List my Coolify applications with their names, UUIDs, and statuses. Do not make any changes.

The example below shows the discovery and API call behind that request. Use a token scoped to the operations you intend to permit.

Build from source

For development or use before the first npm release, install Bun 1.3.8 or newer and Git, then run:

git clone https://github.com/syntropika/coolify-mcp.git
cd coolify-mcp
bun install --frozen-lockfile
bun run build

This builds dist/index.js with the bundled API catalog. Use node as your MCP command and the absolute path to dist/index.js as its single argument. You do not need to regenerate the OpenAPI spec to get started.

For a self-contained executable that does not require Node.js at runtime, run bun run build:native and use the absolute path to dist/coolify-mcp as the command with no arguments. This executable targets the operating system and architecture on which it was built. Native executables are excluded from the npm package.

Example workflow

The agent can get discovery guidance with guide:

{
  "topic": "discovery"
}

Then pass this JavaScript function as the code string to search to find read-only application operations:

async () => {
  return codemode.findOperations({
    tags: ["Applications"],
    mutates: false
  });
}

To list applications, pass this function as the code string to execute:

async () => {
  const apps = await codemode.request({
    operationId: "list-applications",
    throwOnError: true
  });

  return codemode.format.compact(apps.data, ["name", "uuid", "status"]);
}

This makes a read-only API call and returns only those three fields for each application. For composed workflows and request previews, see the Code Mode guide and tool reference.

Configuration

| Variable | Purpose | Default | | --- | --- | --- | | COOLIFY_BASE_URL | Coolify instance origin or API root. Required for execute. | None | | COOLIFY_API_TOKEN | API token used for Coolify requests. Required for execute. | None | | COOLIFY_OPENAPI_PATH | Absolute path to a custom OpenAPI JSON file. | Bundled spec | | COOLIFY_REQUEST_TIMEOUT_MS | Timeout for each HTTP request, in milliseconds. | 30000 | | COOLIFY_CODE_TIMEOUT_MS | Timeout for Code Mode execution, in milliseconds. | 15000 |

guide and search work without Coolify credentials. execute requires both the URL and token, including when dryRun is enabled. Each search or execute call can also set timeoutMs; see the tool reference.

Safety model

• DELETE is opt-in. Requests with the DELETE method require allowDestructive: true on the outer execute call, including during a dry run.
• Other mutations are not gated by that flag. Deploy, start, stop, restart, enable, and disable may use GET endpoints. The catalog classifies their side effects; the HTTP method alone does not establish whether a call is read-only.
• Preview requests with dryRun: true. It returns request plans without sending HTTP requests, with classifications and guidance for catalog operations. It does not simulate API responses or validate a workflow against live state.
• Choose what leaves the runtime. Use selected fields, codemode.format.tsv(), or codemode.format.compact() for summaries. Call codemode.redactSecrets() before returning environment variables, keys, tokens, credentials, or headers, and inspect the output for secrets.
• Use trusted clients and scoped tokens. The token stays in the host process; generated code receives a request helper and has no direct process, require, filesystem, or fetch binding. The Node.js VM is a local guardrail, not a security isolation boundary. Coolify token scopes provide final authorization.

Documentation

• Tool reference: tool inputs, sandbox APIs, request types, and dry-run behavior.
• Code Mode guide: composed workflows and runtime design.
• Operation coverage: every operation in the bundled catalog.
• Agent skill: reusable guidance for agents operating Coolify.

Contributing

Found a confusing setup step or an operation that needs better guidance? Open an issue with a reproducible example and secrets removed. Documentation improvements and focused pull requests are welcome.

Check the bundled snapshot before submitting a change:

bun run typecheck
bun run test
bun run test:package

For maintainers, bun run generate fetches the upstream Coolify v4.x OpenAPI spec and rewrites the bundled spec and operation docs. Review catalog changes and update the coverage expectations when refreshing it. bun run verify performs that refresh before typechecking, tests, and a build, so it can surface upstream changes beyond your local edit.

Publishing to npm

The public package is @j0nl1/coolify-mcp, and its executable is coolify-mcp. Publishing requires access to the j0nl1 npm account, Node.js, npm, and Bun. The project .npmrc directs the @j0nl1 scope to npm rather than GitHub Packages; publishConfig sets the public registry and public access.

bun install --frozen-lockfile
bun run typecheck
bun run test
bun run test:package
npm pack --dry-run
npm login --registry=https://registry.npmjs.org/
npm whoami --registry=https://registry.npmjs.org/
npm publish

Confirm that npm whoami returns j0nl1 before publishing. prepublishOnly runs typechecking and unit tests; prepack rebuilds the portable Node.js entry point. test:package packs the release, installs it in an isolated directory without install scripts, and checks MCP discovery, search, and dry-run execution on Node.js without contacting Coolify. Temporary package test artifacts are stored outside the repository and removed afterward.

For subsequent releases, update the version in package.json, the server version in src/index.ts, and the pinned installation examples before publishing. npm versions cannot be overwritten.

If this is useful for your Coolify setup, star the repository to help others find it.

License

MIT.