Coolify MCP

coolify-mcp

Coolify API 用の MCP サーバーです。ゼロから本番環境までのデプロイワークフローをすべて実行できます。

Coolify v4.3.10 API を対象としています。型とスキーマは Coolify 公式の OpenAPI 仕様から直接生成されるため、ツールの入力は常に API が実際に受け付ける内容と一致します。

特長

• 完全なデプロイワークフロー：プロジェクト、環境、サーバー、アプリケーションをゼロから作成できます
• 5 種類のアプリケーション：createApplication ツールで、公開 Git、GitHub App、Deploy Key、Dockerfile、Docker Image の各ソースを作成できます。さらに、createService で Docker Compose のデプロイにも対応します（Coolify v4.1 以降、Compose のデプロイはサービスとして扱われます）
• 環境管理：秘密情報をマスキングしながら、環境変数の作成・読み取り・更新・削除をすべて実行できます
• デプロイ制御：アプリケーションのデプロイ（任意で終了ステータスまで待機し、失敗時にはログ末尾を表示）、起動、停止、再起動ができます
• 診断：diagnoseApp は UUID、名前、ドメインでアプリを検索し、ステータス、最近のデプロイ、失敗時のログ末尾、ランタイムログ、推奨される次のアクションをまとめて表示します
• ドキュメント検索：searchDocs は、同梱されたローカルインデックスを使って Coolify 公式ドキュメントを全文検索します。ネットワーク接続は不要です
• セキュリティ：書き込み保護、秘密情報の秘匿、MCP アノテーション（readOnlyHint／destructiveHint）に対応しているため、クライアントは読み取りを自動承認し、破壊的な呼び出しを制限できます
• API をほぼ網羅：データベース（8 種類のエンジン、バックアップ、環境変数）、サービス、ストレージ、スケジュールタスク、チーム、プレビュー、サーバー、SSH キー、GitHub Apps に対応しています
• トークン効率に優れる：65 個のツール定義が消費するコンテキストは約 9k トークンです。Coolify の OpenAPI 仕様から生成されたスキーマに基づき、実行時に厳密な検証を行います

要件

• Node 18 以降
• Coolify API トークン（Coolify ダッシュボードの Settings > API）

インストール

Claude Desktop、ワンクリック： 最新リリースから coolify-mcp.mcpb をダウンロードし、Settings → Extensions にドラッグします。Coolify の URL とトークンの入力を求められます。Node のインストールも JSON の編集も不要です。

npm 経由：

npm install -g @fndchagas/coolify-mcp
# or
npx -y @fndchagas/coolify-mcp

クイックスタート

Claude Code CLI

claude mcp add coolify \
  --env COOLIFY_BASE_URL="https://coolify.example.com/api/v1" \
  --env COOLIFY_TOKEN="<token>" \
  -- npx -y @fndchagas/coolify-mcp

OpenAI Codex CLI

codex mcp add coolify \
  --env COOLIFY_BASE_URL="https://coolify.example.com/api/v1" \
  --env COOLIFY_TOKEN="<token>" \
  -- npx -y @fndchagas/coolify-mcp

または ~/.codex/config.toml を編集します。

[mcp_servers.coolify]
command = "npx"
args = ["-y", "@fndchagas/coolify-mcp"]
env = { COOLIFY_BASE_URL = "https://coolify.example.com/api/v1", COOLIFY_TOKEN = "<token>" }

手動設定（~/.mcp.json）

{
  "mcpServers": {
    "coolify": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fndchagas/coolify-mcp"],
      "env": {
        "COOLIFY_BASE_URL": "https://coolify.example.com/api/v1",
        "COOLIFY_TOKEN": "<token>",
        "COOLIFY_ALLOW_WRITE": "true"
      }
    }
  }
}

環境変数

変数	デフォルト	説明
COOLIFY_BASE_URL	必須	Coolify API の URL（例：https://coolify.example.com/api/v1）
COOLIFY_TOKEN	必須	Coolify の Settings > API から取得した API トークン
COOLIFY_ALLOW_WRITE	true	書き込み操作（作成、更新、削除、デプロイ）を有効にします
COOLIFY_STRICT_VERSION	false	API のバージョンが一致しない場合に失敗させます
COOLIFY_MCP_ELICITATION	on	破壊的な削除時の人間による確認をスキップするには、off に設定します（エリシテーションを通知するものの、実装していないクライアント向けの回避策です）
MCP_TRANSPORT	stdio	トランスポート：stdio、http、both
PORT	7331	HTTP ポート（http トランスポートを使用する場合）
MCP_HTTP_TOKEN	未設定	/mcp リクエストで必要なベアラートークン（HTTP トランスポート）。設定すると、デフォルトのバインド先も 0.0.0.0 に切り替わります
MCP_HTTP_HOST	127.0.0.1（トークン設定時は 0.0.0.0）	HTTP トランスポートのバインド先インターフェース。トークンなしでループバック以外にバインドすると、強い警告がログに記録されます

ゼロからデプロイする

この MCP を使えば、アプリケーションをゼロからデプロイできます。

1. listProjects / createProject       → Get or create a project
2. listEnvironments / createEnvironment → Get or create an environment
3. listServers / createServer         → Get or create a server
4. listPrivateKeys / createPrivateKey → Get or create SSH keys (if needed)
5. createApplication (type: public)   → Create the application
6. applicationEnvs (action: upsert)   → Configure environment variables
7. deploy                             → Trigger deployment

ツールのリファレンス

プロジェクトと環境

ツール	説明	書き込み
listProjects	すべてのプロジェクトを一覧表示します
createProject	新しいプロジェクトを作成します	✓
updateProject	プロジェクト名／説明を更新します	✓
deleteProject	プロジェクトとそのすべてのリソースを削除します	✓
listEnvironments	プロジェクト内の環境を一覧表示します
createEnvironment	新しい環境を作成します	✓

サーバーとインフラストラクチャ

ツール	説明	書き込み
listServers	すべてのサーバーを一覧表示します
getServer	サーバーの詳細を取得します
createServer	新しいサーバーを作成します	✓
validateServer	サーバー接続を検証します
listPrivateKeys	SSH 秘密鍵を一覧表示します
createPrivateKey	新しい SSH 鍵を作成します	✓
listGithubApps	設定済みの GitHub Apps を一覧表示します

アプリケーション - 読み取り

ツール	説明
listApplications	すべてのアプリケーションを一覧表示します（デフォルトでは要約表示）
getApplication	アプリケーションの詳細を取得します（デフォルトではシークレットをマスクします）
getLogs	アプリケーションの実行時ログを取得します

アプリケーション - 作成

ツール	説明	書き込み
createApplication	アプリケーションを作成します。type でソースを選択します：public、private-github-app、private-deploy-key、dockerfile、または dockerimage。その他の追加フィールドは extra に指定し、タイプごとに検証されます。	✓

Docker Compose のデプロイは、docker_compose_raw を渡して createService で作成します。Coolify v4.1 以降、これらはアプリケーションではなくサービスです。

アプリケーション - 管理

ツール	説明	書き込み
updateApplication	アプリケーションの設定を更新します	✓
deleteApplication	アプリケーションを削除します	✓
startApplication	アプリケーションを起動します	✓
stopApplication	アプリケーションを停止します	✓
restartApplication	アプリケーションを再起動します	✓

環境変数

ツール	説明	書き込み
applicationEnvs	アプリケーションの環境変数を管理します：一覧表示（デフォルトではマスク）、作成、更新、キーによるアップサート、一括更新、削除	✓

データベースとサービスの環境変数には、それぞれ専用のツール databaseEnvs と serviceEnvs があります。

デプロイ

ツール	説明	書き込み
deploy	デプロイを開始します。wait: true の場合は、最終ステータスになるまでポーリングし、失敗時にはログの末尾を返します	✓
diagnoseApp	UUID、名前、またはドメインでアプリを診断します：ステータス、最近のデプロイ、失敗時のログの末尾、ランタイムログ、ヒント
diagnoseServer	UUID、名前、または IP でサーバーを診断します：リソースのステータス内訳、ドメイン、ヒント
listDeployments	実行中のデプロイを一覧表示します
getDeployment	デプロイのステータスとログを取得します
listAppDeployments	アプリケーションのデプロイを一覧表示します
cancelDeployment	実行中のデプロイをキャンセルします	✓

データベース

ツール	説明	書き込み
listDatabases	すべてのデータベースを一覧表示します
getDatabase	データベースの詳細を取得します
createDatabase	データベースを作成します。type でエンジンを選択します：postgresql、mysql、mariadb、mongodb、redis、keydb、dragonfly、clickhouse	✓
updateDatabase	データベースの設定を更新します	✓
deleteDatabase	データベースを削除します（デフォルトではボリュームと設定も削除されます）	✓
controlDatabase	データベースを起動、停止、または再起動します	✓
databaseBackups	バックアップのスケジュールと実行を管理します（list/create/update/delete/list_executions/delete_execution）	✓
databaseEnvs	データベースの環境変数を管理します（list/create/update/bulk_update/delete）	✓

サービス

ツール	説明	書き込み
listServices	サービスを一覧表示します
getService	サービスの詳細を取得します（シークレットはデフォルトでマスクされます）
createService	ワンクリックサービスまたは Docker Compose デプロイを作成します	✓
updateService	サービスを更新します	✓
deleteService	サービスを削除します	✓
controlService	サービスを起動、停止、または再起動します	✓
serviceEnvs	サービスの環境変数を管理します（list/create/update/bulk_update/delete）	✓

ストレージ、スケジュールタスク、プレビュー

ツール	説明	書き込み
storages	アプリケーション、データベース、サービスの永続ボリュームとファイルマウントを管理します	✓
scheduledTasks	実行履歴を含む、アプリケーションとサービスの cron タスクを管理します	✓
deletePreview	プルリクエスト ID でプレビューデプロイを削除します	✓

チーム、サーバー、Git

ツール	説明	書き込み
teams	チームの一覧表示、現在のチームの取得、メンバーの一覧表示を行います
updateServer	サーバーの設定を更新します	✓
deleteServer	サーバーを削除します	✓
getServerResources	サーバー上で実行中のリソースを一覧表示します
getServerDomains	サーバーに設定されているドメインを一覧表示します
getPrivateKey	SSH キーのメタデータを取得します（キーの内容はデフォルトでマスクされます）
updatePrivateKey	SSH 秘密鍵を更新します	✓
deletePrivateKey	SSH 秘密鍵を削除します	✓
getGithubAppRepositories	GitHub App がアクセスできるリポジトリを一覧表示します
getGithubAppBranches	リポジトリのブランチを一覧表示します

一括操作

ツール	説明	書き込み
getInfrastructureOverview	サーバー、プロジェクト、アプリケーション（ステータス内訳）、データベース、サービス、実行中のデプロイをまとめて取得します
restartProjectApps	プロジェクトまたは環境内のすべてのアプリケーションを再起動します（確認を求めます）	✓
redeployProject	プロジェクトまたは環境内のすべてのアプリケーションのデプロイを開始します（確認を求めます）	✓
stopAllApplications	実行中のすべてのアプリケーションを緊急停止します。プロジェクト単位での停止も可能です（影響範囲を示して確認を求めます）	✓

その他

ツール	説明
listResources	フィルターを適用してすべてのリソースを一覧表示します
searchDocs	Coolify 公式ドキュメントを全文検索します（インデックスを同梱しており、ネットワーク接続は不要です）
getHealth	Coolify API が稼働していることを確認します

セキュリティ機能

書き込み保護

すべての書き込み操作を無効にします：

COOLIFY_ALLOW_WRITE=false

シークレットのマスキング

• 環境変数の値はデフォルトでマスキングされます
• データベースの認証情報は伏せられます
• 必要な場合に限り、showSecrets: true を使用してください

HTTP トランスポートの強化

HTTP トランスポートはデフォルトで 127.0.0.1 にバインドします。ループバック以外にも公開するには、MCP_HTTP_TOKEN を設定してください。以降、/mcp へのすべてのリクエストに Authorization: Bearer <token>（定数時間で検証）が必要になり、バインド先は 0.0.0.0 に切り替わります（MCP_HTTP_HOST で上書きできます）。トークンなしでループバック以外のホストにバインドすると、ポートにアクセスできる人なら誰でも Coolify インスタンスを操作できることを示す、目立つ警告がログに記録されます。

破壊的な削除の前に人間が確認

elicitation に対応した MCP クライアント（Claude Code、VS Code Copilot）では、プロジェクト、アプリケーション、データベース、サービス、サーバー、または秘密鍵を削除する前に、何が失われるかを明示して、ユーザーに確認を求めます。elicitation に対応していないクライアントの動作は従来どおりです。拒否、キャンセル、またはタイムアウトの場合、呼び出しは中止されます。プロンプトを完全に無効にするには、COOLIFY_MCP_ELICITATION=off を設定してください。

開発

git clone https://github.com/frndchagas/coolify-mcp.git
cd coolify-mcp
npm install
npm run dev

スクリプト

npm run dev            # Run in development mode
npm run build          # Build TypeScript
npm run generate       # Fetch the pinned OpenAPI spec and regenerate types

Coolify の固定バージョン

バージョンは src/coolify/constants.ts で定義されています。更新するには：

1. src/coolify/constants.ts の COOLIFY_VERSION を編集します
2. npm run generate を実行します

レジストリ掲載情報

• MCP レジストリ：io.github.frndchagas/coolify-mcp

MCP クライアントの例

HTTP クライアント

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);

// List all applications
const apps = await client.callTool({
  name: 'listApplications',
  arguments: {},
});
console.log(apps.structuredContent);

// Deploy an application
const deploy = await client.callTool({
  name: 'deploy',
  arguments: { uuid: 'your-app-uuid' },
});
console.log(deploy.structuredContent);

await client.close();

Stdio クライアント

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = new Client({ name: 'coolify-client', version: '1.0.0' });
const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@fndchagas/coolify-mcp'],
  env: {
    COOLIFY_BASE_URL: 'https://coolify.example.com/api/v1',
    COOLIFY_TOKEN: '<token>',
  },
});

await client.connect(transport);

const result = await client.callTool({
  name: 'getApplication',
  arguments: { uuid: 'your-app-uuid' },
});
console.log(result.structuredContent);

await client.close();

ライセンス

MIT