awesome-coolify

awesome-coolify-mcp

コーディングエージェントからCoolifyを操作できます。
接続を検証し、インフラを検出し、ワークロードを作成し、デプロイし、ログを追跡し、インシデントを診断し、承認ゲート付きの緊急操作を実行できます。セルフホストまたはCloudの1つ、あるいは複数のインスタンスを対象に、
Cursor、Claude、VS Code、Windsurf、またはMCPに対応した任意のエージェントから直接操作できます。

🇩🇪 ドイツ語 · Coolify · Model Context Protocol · インストール設定ツール ↗

概要 · 選ばれる理由 · 機能 · アーキテクチャ · クイックスタート · インストール · Cloud · ツール · プロンプト · 安全性 · ロードマップ

  

_{ワンクリックでプレースホルダーの認証情報を使ってインストールできます。詳しい手順はインストールを参照するか、ブラウザー設定ツールを使って実際の値を安全に入力してください。}

---

📋 目次

• 概要
• awesome-coolify-mcp を選ぶ理由
• 機能
• 仕組み
• クイックスタート
• インストール
  • 1. ワンクリックディープリンク
  • 2. インストール設定ツール
  • 3. MCP の手動設定
• Coolify Cloud
• 対応クライアント
• 環境変数
• MCP プロンプト
• ツールリファレンス
• 安全性モデル
• 構造化エラーと再試行
• エージェントのワークフロー例
• 現在のステータス
• 今後の予定
• ローカル開発
• リンク

---

🔭 概要

セルフホスト可能な Coolify は、Heroku や Vercel のような PaaS プラットフォームに代わる、優れたオープンソースの選択肢のひとつです。しかし、AI コーディングエージェントと連携させるには、これまで複数の小規模で機能が重複するコミュニティ製 MCP 統合をつなぎ合わせる必要がありました。それぞれ独自のスキーマやエラー形式を持ち、「安全」の捉え方も異なっていました。

awesome-coolify-mcp 1.1.4 は、こうした継ぎはぎの状態を、明確な アクションベースのツール群を通じて Coolify の REST API 4.1.x を利用する、コミュニティが保守する単一の MCP サーバーに置き換えます。ソースコード、ドキュメント、npm パッケージは、ひとつの公開リポジトリ clezcoding/awesome-coolify にまとめられており、インストール可能なパッケージ名は awesome-coolify-mcp のままです。似たようなツール名をいくつも覚える代わりに、エージェントは action フィールドを使って 19 個のツールのいずれかを呼び出します。

application({ action: "deploy", uuid: "<app-uuid>", wait: false })
deployment({ action: "watch", deployment_uuid: "<deployment_uuid>", timeout: 300 })
diagnose({ action: "scan" })
emergency({ action: "stop_all", confirm: true })

内部では、すべての呼び出しが同じリクエスト処理パイプラインを通ります。Zod による入力検証、再試行に対応した HTTP クライアント、シークレットを考慮した出力のマスキング、復旧のヒントを含む構造化エラーエンベロープを利用するため、エージェントは推測に頼ることなく、適切にエラーに対処できます。

メモ

これは、自分で Coolify インスタンスを運用する人向けのコミュニティプロジェクトです。Coolify Labs とは提携しておらず、同社から推奨も受けていません。

🆚 awesome-coolify-mcp を選ぶ理由

一般的なセットアップの場合	awesome-coolify-mcp を使う場合
スキーマがそれぞれ異なる、重複の多いコミュニティ製 MCP ツールが複数あります	1 つのサーバー、1 つの一貫したスキーマ
リソースごとに、細分化された単機能ツールが数十個あります	一貫した action ディスクリミネーターを備えた 19 個のツール
エージェントが推測しなければならない、その場しのぎのエラー文字列	構造化コード（COOLIFY_401、COOLIFY_404、…）と、機械可読な復旧ヒント
シークレットがエージェントのコンテキストにそのまま漏れる可能性があります	デフォルトでシークレットをマスキングし、破壊的な操作には確認ゲートを設けます
変更点を探すために、大量の生 JSON を読む必要があります	LLM のコンテキストウィンドウに合わせて調整された、件数を制限したページネーション付きのデータ

現在、提供されている機能は、日常的な運用とインフラの作成をカバーしています。接続の確認、フリートの把握、デプロイとビルドの監視、ログの範囲を制限した確認、インシデントの診断、確認ゲート付きの緊急操作に加えて、アプリケーション、サービス、データベース、SSH キー、サーバー、プロジェクト、環境、バックアップ、環境変数を管理できます。

---

✨ 特長

• 19 個のアクションベースのツール — 細分化された多数のツール名から探す代わりに、application({ action: "deploy", uuid }) を呼び出せます。登録されているツールは system、meta、resource、diagnose、application、emergency、deployment、service、database、private_key、instance、manifest、server、project、environment、docs、recipe、setup、intelligence です。
• マルチインスタンスのレジストリとルーティング — instance ツールを使って、所有するすべての Coolify インスタンスを ~/.coolify-mcp/instances.json に登録できます。呼び出しごとに認証情報を解決し、インスタンス間で情報が漏れません。
• Coolify Cloud に対応 — instance({ action: "cloud-info" }) でローカル環境の検出、チーム単位のトークン、構造化されたクラウドエラーコード（COOLIFY_CLOUD_FORBIDDEN、COOLIFY_CLOUD_UNSUPPORTED）を利用できます。
• ローカルマニフェストキャッシュ — manifest({ action: "sync" }) で .coolify/manifest.json を同期し、アプリ／サービス／DB の変更時にはベストエフォートで自動フックを実行します。キャッシュが古い場合は _meta.manifestWarning を返します。
• サーバーのブランディング — serverInfo.icons による MCP リストアイコン（docs/assets/ のデータ URI 埋め込み版と jsDelivr CDN エントリー）。
• 実際のインシデントに即した運用ワークフロー — 全体像を把握する単一の system.infrastructure_overview 呼び出し、名前やドメインだけ覚えている場合のあいまい検索 resource.find、特定の疑わしい対象を調べる diagnose.app／diagnose.server、フリート全体のどこかに問題があると分かっている場合の diagnose.scan を利用できます。
• エージェントが実行できるデプロイのライフサイクル — 起動／停止／再起動、強制再ビルド、バックオフの上限を設けた deployment.watch、ビルド用の deployment.logs、件数を制限した application.logs、アイドルタイムアウトと全体タイムアウトを備えた実行時の追跡に対応します。
• ワークロード全体の CRUD — アプリケーション、サービス、データベースの作成、確認、更新、削除、操作ができます。service.list-types で、現在利用できるワンクリック ID を確認できます。
• レシピとガイド付きセットアップ — Git アプリ、アプリとデータベースのスタック、ワンクリックサービスを作成できます。setup.preflight、setup.wire、setup.resume を実行でき、対応する IDE ワークフロースキルを 4 つインストールできます。
• 慣習ではなく、デフォルトで安全 — 緊急の変更操作には confirm: true が明示的に必要です。機密性の高いキー（password、token、secret、private、env）は、reveal: true を指定しない限り *** と表示されます。
• エージェントに適したエラー処理 — すべてのエラーは、code、人が読める message、recoveryHints を含む解析可能なエンベロープです。一時的なネットワークエラー／429／5xx エラーは、指数バックオフで自動的に再試行されます。
• 幅広いクライアントに標準で対応 — Cursor、VS Code / GitHub Copilot、Claude Desktop、Claude Code、Windsurf など 15 以上に、インストール設定ツールから対応します。

---

🏗️ 仕組み

MCP client (Cursor / Claude / VS Code / …)
        │  stdio MCP
        ▼
awesome-coolify-mcp  (19 tools + action discriminator)
        │  optional ~/.coolify-mcp/instances.json resolution
        │  HTTPS + Bearer token
        ▼
Coolify REST API 4.1.x  (servers · projects · applications · services · databases)

サーバー自体は意図的にシンプルに設計されています。長期間保持する状態はなく、IDE の設定ファイルに触れることもありません。MCP ホスト（Cursor、Claude、VS Code など）が、MCP 設定の env ブロックを通じて COOLIFY_URL と COOLIFY_TOKEN を注入するか、instance ツールを使って ~/.coolify-mcp/instances.json に名前付きインスタンスを登録します。プロセスは環境変数（またはレジストリ）から認証情報を読み取り、認証済みのリクエストを HTTPS 経由で Coolify インスタンスに転送します。

---

🚀 クイックスタート

前提条件

• Node.js 24+（Active LTS。CI では Node 24 を使用）
• 4.1.x のセルフホスト可能な Coolify インスタンス
• Coolify → Keys & Tokens で取得した API トークン（認証ドキュメント）

グローバルインストールは不要です。npx で直接実行できます。

npx -y awesome-coolify-mcp

必須の環境変数 2 つを MCP ホストに設定します（各クライアントについてはインストールを参照）。接続後、最小限のスモークテストは次のようになります。

meta({ action: "version" })                       // server identity — no Coolify call
system({ action: "verify" })                      // authenticate + connectivity check
system({ action: "infrastructure_overview" })     // servers, projects, apps, services, DBs at a glance

メモ

複数インスタンスを利用する場合： まず instance({ action: "add", name, url, token }) で各 Coolify インスタンスを登録し、その後 system({ action: "verify" }) を呼び出してください。単一インスタンス構成では、レジストリへの登録を省略し、MCP の環境変数に COOLIFY_URL / COOLIFY_TOKEN を設定できます。

重要

緊急操作（stop_all、redeploy_project、restart_project）には confirm: true が必要です。最初は confirm を付けずに呼び出してください。変更は実行されず、would_affect プレビューが返されます。平文のシークレットが本当に必要な場合に限り、reveal: true を渡してください。

---

📦 インストール

同等にサポートされている方法が 3 つあります。ワークフローに合った方法を選んでください。

1. ワンクリックのディープリンク

Coolify の URL とトークンが手元にある場合に最適です。プレースホルダーの認証情報でも問題ありません。入力を求められるか、後から置き換えることができます。

  

これらのリンクの仕組み（クリックして展開）

どちらのエディターも、URL から JSON サーバー設定を直接読み取るプロトコルハンドラーを実装しています。

クライアント	スキーム	エンコード
Cursor	cursor://anysphere.cursor-deeplink/mcp/install?name=…&config=…（わかりやすいランディングページとして https://cursor.com/en/install-mcp?… にもミラーされています）	config は Base64 エンコードされた JSON です
VS Code / Copilot	vscode:mcp/install?name=…&config=…	config は URL エンコードされた JSON です

ボタンをクリックするとエディターが開き、追加しようとしているサーバーが表示されます。承認する前にコマンドや環境変数を確認・編集できます。何も通知されずにインストールされることはありません。

2. インストール設定ツール（GitHub Pages）

**ブラウザー設定ツール**で実際の COOLIFY_URL / COOLIFY_TOKEN を入力すると、使用するクライアントに合わせた貼り付け用スニペットを生成できます。クライアントの形式に応じて JSON、TOML、または YAML が生成されます。

すべての処理はブラウザー内のクライアント側で実行されます。トークンがバックエンドに送信されたり、ログに記録されたり、貼り付け先の設定ファイル以外に保存されたりすることはありません。

3. MCP 設定を手動で行う

ホストの MCP 設定ファイルに貼り付けてください。Cursor の例（グローバル設定の場合は ~/.cursor/mcp.json、プロジェクトの場合は .cursor/mcp.json）：

{
  "mcpServers": {
    "awesome-coolify-mcp": {
      "command": "npx",
      "args": ["-y", "awesome-coolify-mcp"],
      "env": {
        "COOLIFY_URL": "https://coolify.example.com",
        "COOLIFY_TOKEN": "YOUR_COOLIFY_API_TOKEN",
        "COOLIFY_VERIFY_SSL": "true",
        "COOLIFY_MCP_LOG": "info"
      }
    }
  }
}

すぐにコピーして貼り付けられるテンプレートは、docs/mcp.example.json にもあります。

ヒント

Coolify Cloud をお使いですか？チームスコープのトークンを生成し、docs/en/cloud.md のレジストリ設定に従ってください。

IDE スキル（Cursor、Claude Code、Codex）

Cursor、Claude Code、Codex 用の Coolify ワークフロースキルをインストールします。

npx skills add clezcoding/awesome-coolify -a cursor -a claude-code -a codex

MCP のインストール後、setup({ action: "preflight" }) を実行するか、gh のプリフライト、プロジェクトのリンク、グリーンフィールドのプロビジョニングについては**セットアップガイド**を参照してください。

---

🖥️ 対応クライアント

クライアント	設定場所	備考
Cursor	~/.cursor/mcp.json	ワンクリックのディープリンク、または手動で JSON を設定
VS Code / GitHub Copilot	.vscode/mcp.json	URL／トークンの入力を求めるネイティブの inputs — ファイルに平文で保存されません
Claude Desktop	claude_desktop_config.json	現在は手動の JSON 設定、またはコンフィギュレーターの出力を使用
Claude Code	~/.claude.json or .mcp.json	npx -y awesome-coolify-mcp 経由の stdio
Windsurf	~/.codeium/windsurf/mcp_config.json	Cursor と同じ npx ＋ env パターン

インストールコンフィギュレーター では、さらに幅広いクライアントに対応しています。OpenCode、Codex CLI、Gemini CLI、Cline、Kilo Code、Goose、LM Studio、Hermes Agent、Kimi Code、Google Antigravity、OpenClaw など、それぞれに適した設定形式を提供します。

メモ

Claude Desktop では現在、手動の JSON 設定またはコンフィギュレーターの出力を使用します。

---

🔐 環境変数

変数	必須	デフォルト	説明
COOLIFY_URL	はい*	—	Coolify のベース URL。末尾にスラッシュを付けないでください。例：https://coolify.example.com
COOLIFY_TOKEN	はい*	—	チームにスコープを設定した Bearer API トークン
COOLIFY_VERIFY_SSL	いいえ	true	ローカル／開発用インスタンスで自己署名証明書を使用する場合に限り、false に設定します
COOLIFY_MCP_LOG	いいえ	info	ログの詳細度：debug · info · error

認証情報は、プロセス環境（IDE の MCP env ブロック）または CLI を直接実行するときに使用する任意のローカル .env ファイルから読み込まれます。ツールの応答に認証情報が含まれることはありません。

メモ

マルチインスタンスレジストリ（~/.coolify-mcp/instances.json）を使用すると、COOLIFY_URL と COOLIFY_TOKEN は省略可能になり、instance ツールが呼び出しごとに認証情報を解決します。環境変数は、単一インスタンス構成で最も簡単に使える方法です。

---

☁️ Coolify Cloud

awesome-coolify-mcp は、同じ 19 個のツールを使って Coolify Cloud で動作します。チームスコープのトークン、構造化されたクラウドエラーコード（COOLIFY_CLOUD_FORBIDDEN、COOLIFY_CLOUD_UNSUPPORTED）、および検出用のローカル instance アクション cloud-info に対応しています。

最初の Cloud セッションの前に instance({ action: "cloud-info" }) を実行してください。isCloud、解決済みの url、認証情報の source（registry | env | infer）、knownLimits、ドキュメントへのリンクが返されます。ライブ API 呼び出しは行われません。

完全なセットアップ、スモークテスト、既知の制限事項 → docs/en/cloud.md

---

💬 MCP プロンプト

6 つのパラメーター化されたワークフロープロンプトは、既存のツールを連携させる、番号付きの手順ガイダンス（英語の本文）を返します。引数のほとんどは省略可能です。事前入力なしで任意のプロンプトを開けます。

プロンプト	引数（特記がない限りすべて省略可能）	用途
deploy	instance?、uuid?、force?	アプリケーションをデプロイし、終端ステータスになるまで監視します
diagnose	instance?、uuid?	アプリ、サーバー、またはフリート全体の問題を調査します（diagnose.analyze を含む）
new-project	instance?、name?、server_uuid?	プロジェクト、環境、および任意のサーバーリンクを作成します
incident	instance?、uuid?、project_uuid?	diagnose.analyze、ログ、再起動、または緊急再デプロイでトリアージします
rollback	instance?、uuid?、name?	プレビュー後、人間の承認を求める deployment.rollback を実行します（人間の承認があるまで停止）
maintenance-window	instance?、uuid?、resource_type	既存の確認必須の変更操作を使用し、変更ウィンドウをガイドします

プロンプトハンドラーは、ディスクから .coolify/manifest.json を読み取りません。エージェントにマニフェストから UUID を解決するよう促すか、ユーザーに尋ねるよう案内します。プレイブックが confirm: true を自動設定することはありません。

---

🧰 ツールリファレンス

各ドメインは action ディスクリミネーターを備えた 1 つの MCP ツールとして公開されるため、機能の範囲を広く保ちながら、エージェントのツール一覧を短くできます。

system({ action: "health" })
application({ action: "deploy", uuid: "<app-uuid>", wait: false })
deployment({ action: "watch", deployment_uuid: "<deployment_uuid>", timeout: 300 })
emergency({ action: "stop_all", confirm: true })

🖥️ system — 接続性と概要

セッションで最初に呼び出すアクションです。Coolify に接続できるか、また現在のフリートがどのような状態かを確認します。

アクション	目的
health	Coolify API への接続性を確認します
version	Coolify インスタンスのバージョン文字列を取得します
verify	認証を行い、1 回の呼び出しで接続性とバージョンを返します
infrastructure_overview	サーバー、プロジェクト、アプリケーション、サービス、データベース全体の集計件数を取得します

🏷️ meta — サーバーの識別情報

アクション	目的
version	awesome-coolify-mcp 自体のパッケージ名と semver を取得します — Coolify への呼び出しは一切行いません

🔎 resource — 検索

探しているものはおおよそ分かっていても、正確な UUID が分からない場合に使用します。

アクション	目的
list	アプリケーション、サービス、データベースを要約形式で一覧表示し、ページネーション用の _meta を返します
find	サーバーとリソースを対象に、名前、ドメイン、IP であいまい検索します — 順位付けされ、最大 10 件に制限されます

🩺 diagnose — 調査

何かがおかしいと感じても、まだ原因が分からないときに使うツールです。

アクション	目的
app	アプリのステータス、ヘルス、環境変数の件数、最近のデプロイを確認します
server	サーバーのリソース、ドメイン、接続性を確認します
scan	フリート全体の問題を重大度別に分類します — 「何が危機的な状態か」を確認するボタンです
logs	アプリケーションを特定してトリアージ用のコンテキストを返し、必要に応じて上限付きのランタイムログまたはデプロイログを含めます
analyze	Log Brain — ランタイムログ（および任意でビルドログ）をルールベースでパターン・トリアージします。参考情報のみを提供します（crash_loop、OOM など）

🚀 application — アプリの操作

アクション	目的
get	アプリケーションの詳細な設定を取得します
start / stop / restart	コンテナーのライフサイクルを制御します
deploy	任意の force リビルドを指定してデプロイを開始します。wait: false と deployment.watch（推奨）、または従来の wait: true によるポーリングを使用します
logs	上限付きのランタイムログ、またはアイドルタイムアウトと全体タイムアウトを指定した上限付きの追跡モードを取得します
envs:list / envs:get	環境変数を一覧表示または取得します（reveal: true でない限り、値は *** としてマスクされます）
envs:create / envs:update	環境変数を個別に作成または更新します（is_preview、is_literal、is_multiline、is_shown_once に対応）
envs:delete	環境変数を 1 つ削除します — confirm: true が必要です
envs:bulk-update	複数の環境変数を一度にパッチします — confirm: true が必要です
envs:sync	ローカルの .env ファイルまたはインラインコンテンツとの差分を確認し、適用します — アプリケーションのみ。リソースの環境変数を参照してください
envs:promote	同じ Coolify インスタンス内の 2 つのアプリケーション間で環境変数を比較し、昇格します（製品名：env.promote）。デフォルトではプレビューのみです — リソースの環境変数を参照してください

📈 deployment — デプロイの追跡

アクション	目的
list	指定したアプリケーションのデプロイを一覧表示します
get	1 件のデプロイのステータス、コミット、タイミングの詳細を取得します
watch	上限付きのタイムアウト、バックオフ、ジッターを適用しながら、終端状態になるまでポーリングします
cancel	実行中のデプロイを安全にキャンセルします
logs	デプロイ UUID を指定して上限付きのデプロイビルドログを取得するか、アプリケーションの最新デプロイのログを取得します
preflight	参考情報のみを提供する読み取り専用のデプロイリスクチェックです：instance_health、env_completeness、recent_deployment_failures、dns_readiness → risk_score / risk_level。環境変数の値はマスクされ、ライブ DNS プローブは行いません
rollback	最新のデプロイがすでに finished の場合に、以前の成功した finished デプロイへ復旧します（確認が必要）。成功したデプロイが 1 件しかない場合は COOLIFY_ROLLBACK_UNAVAILABLE エラーが発生します — Git アプリでは updateApplication で git_commit_sha を固定してから triggerDeploy を実行します。confirm: true がない場合はプレビューのみです

🛡️ デプロイガード（preflight + rollback）

アクション	安全性
preflight	読み取り専用 — デプロイ／変更 API は呼び出しません。advisory: true。リスクが重大、またはデプロイが進行中の場合は blocking になります
rollback	緊急操作と同様の2段階方式です。confirm を省略 → COOLIFY_CONFIRM_REQUIRED + rollback_target のプレビュー（直前に正常終了した finished。すでに終了している場合は現在の先端ではありません）。confirm: true → ピン留めとデプロイを組み合わせて実行します（Coolify に専用のロールバック REST エンドポイントはありません）

deployment({ action: "preflight", uuid: "<app-uuid>" })
// risk acceptable → follow recommended_actions to application.deploy
deployment({ action: "rollback", uuid: "<app-uuid>" }) // preview
deployment({ action: "rollback", uuid: "<app-uuid>", confirm: true, wait: true })

⏱️ Watch — 上限付きデプロイ監視

wait: false を指定して application.deploy を呼び出した後は、deployment.get を手動で繰り返し呼び出すのではなく、deployment.watch を呼び出してください。

動作	詳細
デフォルトのタイムアウト	300秒
ポーリング間隔	3秒で開始し、等ジッターバックオフで最大 30秒まで延長します
タイムアウト後の復旧	同じ deployment_uuid を指定して deployment.watch を再呼び出しします（ビルドに時間がかかる場合は timeout を増やしてください）
失敗／キャンセル	ツールは明確なエラーを返します — 成功として扱わないでください
レガシー	application.deploy wait:true も引き続き動作しますが、後方互換性のためだけのものです。watch を推奨します

application({ action: "deploy", uuid: "<app-uuid>", wait: false })
deployment({ action: "watch", deployment_uuid: "<deployment_uuid>", timeout: 300 })

同梱の IDE スキルパックでも、同じ上限付き watch フローを使用し、タイムアウト後の復旧方法を説明しています。

🧩 service / database — サイドカーのライフサイクル

ツール	アクション
service	get、start、stop、restart、deploy、create（ワンクリックタイプ XOR compose）、update、delete、delete_preview、envs:list、envs:get、envs:create、envs:update、envs:delete、envs:bulk-update
database	get、start、stop、restart、create（8つのエンジン）、update、delete、delete_preview、envs:list、envs:get、envs:create、envs:update、envs:delete、envs:bulk-update、backup:create、backup:list、backup:update、backup:delete、backup:now、backup:history

🍳 recipe — 複数リソースのオーケストレーション

アプリケーションとデータベースの接続、Git アプリ、検証済みのワンクリックサービスなど、一般的なワークロードパターンを1回の MCP 呼び出しで構築します。

アクション	目的
create-git-app	ローカルで build_pack を検出（Dockerfile / Dockerfile.* の glob）し、Git 連携アプリケーションを作成します
create-app-db	データベースとアプリケーションを作成し、両者の間で DATABASE_URL（またはカスタムの env_key）を接続します
create-one-click	ライブの service-templates カタログに対して type を検証した後、ワンクリックサービスを作成します
recommend	ライブの service-templates カタログに基づくアドバイザリーなスタック提案です — リソースは作成しません

安全性： レシピによる作成は意図的な操作であり、確認ゲートはありません。ドライラン／プレビューもありません。一部の処理が失敗しても自動ロールバックは行われません。作成された UUID は error.data で返されます。接続文字列は reveal: true を指定しない限りマスクされます。recommend は読み取り専用／アドバイザリーです。

recipe({ action: "create-git-app", server_uuid, git_repository, git_branch, repo_path: "/path/to/repo" })
recipe({ action: "create-app-db", server_uuid, app_name, db_name, db_engine: "postgresql" })
recipe({ action: "create-one-click", server_uuid, type: "gitea" })
recipe({ action: "recommend", stack: "Next.js + Postgres" })

create-one-click の前に service.list-types も使用して、有効なワンクリックタイプ ID を確認してください。

🌱 リソース環境変数（envs:*）

既存のドメインツールに対する envs:* アクションを通じて、アプリケーション、サービス、データベースの Coolify ランタイム設定を管理します。環境変数用の個別の MCP ツールは不要です。

ツール	envs:* アクション	注記
application	envs:list、envs:get、envs:create、envs:update、envs:delete、envs:bulk-update、envs:sync、envs:promote	ローカルの .env 同期とアプリ間の環境変数昇格に対応する唯一のツール
service	envs:list、envs:get、envs:create、envs:update、envs:delete、envs:bulk-update	同期には非対応です。.env の差分確認／適用には application を使用してください
database	envs:list、envs:get、envs:create、envs:update、envs:delete、envs:bulk-update	データベースの環境変数では is_preview はサポートされていません（Coolify OpenAPI の制約）

確認ゲート： envs:delete と envs:bulk-update では、3つすべてのツールで常に confirm: true が必要です。application のみ、envs:sync では適用時（dry_run: false。デフォルト）または prune: true の場合に confirm: true が必要です。envs:promote では適用時（dry_run: false）に confirm: true が必要です。

値の表示ポリシー： 環境変数の値は、デフォルトで *** として表示されます。人間が平文での表示を明示的に求めた場合にのみ reveal: true を渡してください。エージェントが自動的に reveal: true を設定してはいけません。

envs:sync の動作（application のみ）： env_file（ローカルパス）または env_content（インラインの .env テキスト）のどちらか一方だけを指定します。dry_run: true は API への書き込みを行わず、差分（added、updated、unchanged、removed、任意の conflicts）を返します。デフォルトの dry_run: false では変更を適用します。ローカルに存在しないリモートキーは、prune: true（こちらも confirm: true が必要）を指定しない限り削除されません。ローカルとリモートの値が異なる場合は、人間に確認してから conflict_policy に overwrite、keep_remote、abort のいずれかを設定してください。ポリシーを指定せずに競合がある状態で適用すると、COOLIFY_CONFIRM_REQUIRED が返されます。

envs:promote の動作（application のみ。同一インスタンス内）： 製品ドキュメントでは env.promote と記載されることがありますが、実装されているアクションは application.envs:promote です。source_uuid と target_uuid の間で環境変数を比較します（同じ Coolify インスタンス内の2つのアプリケーションであり、インスタンスをまたいだファンアウトには対応していません）。デフォルトの dry_run: true は、プレビューバケット（only_in_source、only_in_target、value_mismatches）と、後続のツール／アクションのヒントを含む構造化された promotion_suggestions を返します。reveal: true を指定しない限り、値はマスクされます。ターゲットに適用するには confirm: true が必要です。デフォルトの conflict_policy は keep_remote です。人間が overwrite または abort を選択しない限り、値が一致しないターゲットキーはスキップされます。

application({ action: "envs:list", uuid: "<app-uuid>" })
application({ action: "envs:sync", uuid: "<app-uuid>", env_file: "./.env", dry_run: true })
application({ action: "envs:sync", uuid: "<app-uuid>", env_content: "API_KEY=EXAMPLE_VALUE\n", confirm: true, conflict_policy: "overwrite" })
application({ action: "envs:promote", source_uuid: "<source-app-uuid>", target_uuid: "<target-app-uuid>", dry_run: true })
application({ action: "envs:promote", source_uuid: "<source-app-uuid>", target_uuid: "<target-app-uuid>", dry_run: false, confirm: true, conflict_policy: "keep_remote" })

💾 データベースバックアップ（backup:*）

既存の database ツールで、バックアップスケジュールの設定、一覧表示、更新、削除、実行に加え、実行履歴を確認できます。バックアップ専用の MCP ツールはありません。

アクション	目的
backup:create	バックアップスケジュールを作成します（頻度は必須。S3、保持期間、backup_now: true は任意）
backup:list	データベースのバックアップスケジュールを一覧表示します
backup:update	スケジュールのフィールド（頻度、保持期間、S3 フラグ）を更新します
backup:delete	スケジュールを削除します — confirm: true が必要です
backup:now	バックアップを即時実行します
backup:history	スケジュールの実行履歴（ステータス、タイムスタンプ、サイズ）を一覧表示します

親リソースの識別情報： すべてのバックアップアクションで、親データベースを uuid または name で指定する必要があります。スケジュールを対象とするアクション（backup:update、backup:delete、backup:now、backup:history）では、scheduled_backup_uuid も必要です。

確認ゲート： backup:delete には confirm: true が必要です。指定しない場合は COOLIFY_CONFIRM_REQUIRED が返されます。delete_s3 のデフォルトは false（設定のみを削除）です。delete_s3: true の場合も削除には confirm: true が必要です。S3 成果物の消去は破壊的操作として扱われます。

頻度（落とし穴 1）： backup:create は、OpenAPI の名前付きプリセット（every_minute、hourly、daily、weekly、monthly、yearly）または cron 式を受け付けます。backup:update が受け付けるのは プリセットのみ です。更新時に cron 式を渡すと COOLIFY_VALIDATION_ERROR が返されます。

backup:now の動作： スケジュールに対して { backup_now: true } を指定した Coolify の PATCH にマッピングされます。専用のトリガーエンドポイントはありません。scheduled_backup_uuid が必要です。

表示ポリシー： バックアップ設定レスポンス内の S3 関連認証情報は、デフォルトで *** にマスクされます。reveal: true を渡すのは、人間から平文での表示を明示的に求められた場合に限ります。エージェントは reveal: true を自動的に設定してはいけません。

対象外（v2.x 以降）： このリリースでは、バックアップ実行の削除、バックアップからの復元／インポート、S3 ストレージの保存先の CRUD は利用できません。

database({ action: "backup:list", uuid: "<db-uuid>" })
database({ action: "backup:create", uuid: "<db-uuid>", frequency: "daily", save_s3: false })
database({ action: "backup:now", uuid: "<db-uuid>", scheduled_backup_uuid: "<schedule-uuid>" })
database({ action: "backup:delete", uuid: "<db-uuid>", scheduled_backup_uuid: "<schedule-uuid>", confirm: true })

🔑 private_key — SSH キーの CRUD

Coolify の秘密鍵を管理します。PEM の内容はデフォルトでマスクされます。

アクション	目的
list / get	キーを一覧表示または取得します（reveal: true を指定しない限り PEM はマスクされます）
create / update	SSH キーを追加またはローテーションします
delete / delete_preview	キーを削除するか、削除前に依存先をプレビューします

🖧 server — サーバーの CRUD と検証

アクション	目的
get	サーバーの詳細、ドメイン、到達可能性を確認します
create / update	サーバーを登録または再設定します
validate	Coolify のサーバー検証チェックを実行します
delete / delete_preview	サーバーを削除するか、先に依存先をプレビューします

📁 project — プロジェクトの CRUD

アクション	目的
list / get	プロジェクトを検索または確認します
create / update	プロジェクトを作成または名前変更します
delete / delete_preview	プロジェクトを削除するか、先に影響範囲をプレビューします

🌍 environment — 環境の CRUD

アクション	目的
list / get	プロジェクト内の環境を一覧表示または確認します
create	プロジェクトに新しい環境を追加します
delete / delete_preview	環境を削除するか、先に依存先をプレビューします

📚 docs — オフラインガイド

アクション	目的
search	付属の厳選された Coolify トラブルシューティングインデックスを検索します。ライブウェブ取得ではないため、オフラインで動作し、外部取得のベクトルとして使用することはできません

🚨 emergency — 影響の大きい操作（確認が必要）

実行する意図が明確な場合に限って使用してください。以下のすべてのアクションには確認ゲートがあります。

アクション	目的
stop_all	実行中のすべてのアプリケーションを全体で停止します — confirm: true が必要です
redeploy_project	プロジェクト内のすべてのアプリを再デプロイします — confirm: true が必要です
restart_project	プロジェクト内のすべてのアプリを再起動します — confirm: true が必要です

🗂️ instance — マルチインスタンスレジストリ

~/.coolify-mcp/instances.json で名前付きの Coolify インスタンスを管理します。呼び出しごとに認証情報を解決し、インスタンス間で情報が漏れることはありません。

Action	Purpose
list	登録済みインスタンスを一覧表示します（トークンはマスキングされます）
get	名前を指定してインスタンスを取得します
add	新しいインスタンスを登録します（name、url、token、任意の type: "cloud"）
update	既存インスタンスの URL またはトークンをローテーションします
delete	インスタンスを削除します — confirm: true が必要です
set-default	明示的な instance パラメーターがない操作に使用するデフォルトインスタンスを設定します
import-env	オプトイン：プロセス環境変数の COOLIFY_URL と COOLIFY_TOKEN をレジストリにコピーします
cloud-info	ローカルの Cloud 検出情報（isCloud、url、source、knownLimits、ドキュメントへのリンク。API 呼び出しはありません）

instance({ action: "add", name: "prod", url: "https://coolify.example.com", token: "<token>" })
instance({ action: "list" })
instance({ action: "cloud-info" })

📜 manifest — ローカルキャッシュ

.coolify/manifest.json を読み取り、書き込み、同期します。これはワークスペースのキャッシュであり、信頼できる情報源ではありません。UUID が競合した場合はリモートが優先されます。

Action	Purpose
get	ローカルのマニフェストファイルを読み取ります
upsert	プロジェクト、サーバー、リソースをキャッシュにマージします
set	マニフェストのセクションを置き換えます
remove	キャッシュされたリソースエントリーを削除します
clear	マニフェストを消去します — confirm: true が必要です
sync	キャッシュを稼働中の Coolify API と照合します（任意の dry_run、confirm が必要な prune）
diff	非破壊的な差分レポートを作成します — 常に安全に実行できます
audit	読み取り専用／参考情報のドリフト監査：重大度タグ付きの findings[] と、構造化された修正のヒント（次に呼び出すツール／アクション）を返します。任意で diff_support の詳細も含められます — マニフェストも稼働中の状態も変更しません

manifest({ action: "sync", dry_run: true })
manifest({ action: "diff" })
manifest({ action: "audit" })

メモ

manifest.audit は、対象インスタンスのローカル .coolify/manifest.json と稼働中の Coolify インベントリを比較します。検出結果には manifest.sync や manifest.upsert などの後続アクションが示されます。これらのヒントは参考情報にすぎず、自動修復は行われません。未加工の構造的な照合レポートには、引き続き manifest.diff を使用してください。 アプリ／サービス／DB の変更後は、ベストエフォートの自動フックがマニフェストを更新します。ほかの場所で古い UUID による 404 が発生すると、_meta.manifestWarning が表示されます — manifest({ action: "sync" }) を実行して照合してください。

🧭 setup — プロジェクトの接続をガイド

Action	Purpose
preflight	プロジェクトを変更せずに、GitHub CLI とワークスペースの前提条件を確認します
wire	既存のワークロードをリンクするか、新規プロジェクトをプロビジョニングします。オプションで、ドメイン、環境変数の同期、レシピ、マニフェスト、デプロイ監視の各ステップも指定できます
resume	認証など、回復可能な前提条件の確認後に、中断したセットアップを再開します

wire が自動でプッシュすることはありません。gh の認証がない場合、セットアップフローは適切に一時停止し、完了済みのステップから再開します。

🎨 ブランディング（serverInfo.icons）

MCP サーバーは initialize 時に、埋め込み PNG データ URI（プライマリ）と mcp-icon-192.png および favicon-32.png の jsDelivr CDN URL を使ってアイコンを通知します。Cursor では引き続き文字のフォールバックが表示されることがあります — メンテナーの検証記録を参照してください。Coolify API 呼び出しではありません。

---

🛡️ 安全性モデル

確認ゲート

破壊的な緊急操作には、次の厳格な2段階の手順が適用されます。

1. confirm を省略するか false を指定して呼び出します → would_affect のプレビューとエラーコード COOLIFY_CONFIRM_REQUIRED が返されます。変更は一切行われません。
2. confirm: true を指定して再度呼び出します → 操作が実際に実行されます。

通常のアプリ／サービス／データベースの変更（開始、停止、デプロイなど）には、このゲートは適用されません。操作対象はフリート全体ではなく1つのリソースに限定されるため、Coolify 独自の API セマンティクスに従います。

環境変数： envs:delete と envs:bulk-update では、アプリケーション、サービス、データベースで confirm: true が必要です。envs:sync の適用（dry_run: false）と prune: true を指定した envs:sync では、アプリケーションでのみ confirm: true が必要です。dry_run: true の同期プレビューでは変更は行われません。envs:promote の適用（dry_run: false）では、アプリケーションで confirm: true が必要です。デフォルトの conflict_policy は keep_remote です。

ドリフトと修復（読み取り専用の監査、プレビュー優先のプロモーション）： manifest.audit は助言のみを行い、マニフェストや稼働中の状態を書き換えることはありません。application.envs:promote（製品名 env.promote）はデフォルトでプレビューを行います。reveal: true を指定しない限り、値はマスクされたままです。どちらも、1回の呼び出しで1つの Coolify インスタンス内に処理を限定します。

デプロイガード（助言のみの事前チェック、確認必須のロールバック）： deployment.preflight は読み取り専用で、4つの名前付き要因を含む risk_score を返します。外部 DNS／HTTP のプローブは行いません。deployment.rollback では、変更前に confirm: true が必要です。Git のロールバックでは、対象のコミットに対して PATCH を実行してから /deploy に POST します（MCP による複合処理であり、Coolify のロールバック API ではありません）。

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

• password、token、secret、private、env に一致するキーは、ツールの出力でデフォルトで *** として表示されます。
• 平文が明示的に必要な場合に限り reveal: true を指定してください。たとえば、環境変数を別のシステムにコピーする場合です。envs:* の呼び出しで reveal: true を設定する前に、必ず人間に確認してください。
• ログ行の本文はマスクされません。 生のログは、ほかの機密性の高い出力と同様に扱ってください。長期保存されるエージェントのメモリや公開チケットに貼り付けないでください。

警告

レジストリファイル（~/.coolify-mcp/instances.json）は、ディレクトリに 0o700、ファイルに 0o600 の権限を設定して書き込まれます。明示的に reveal: true を指定しない限り、トークンがツールの出力に表示されることはありません。

---

⚠️ 構造化エラーと再試行

すべての API エラーは、生のスタックトレースではなく、エージェントが処理できる解析可能な形式で返されます。

{
  "code": "COOLIFY_401",
  "message": "Unauthorized — invalid or expired API token",
  "recoveryHints": [
    "Verify the token in Coolify UI → Keys & Tokens",
    "Ensure the token has the required team permissions"
  ],
  "httpStatus": 401
}

コード	意味
COOLIFY_401	トークンが無効または指定されていません
COOLIFY_404	リソースが見つかりません
COOLIFY_422	検証エラー
COOLIFY_500	Coolify サーバーエラー
COOLIFY_NETWORK	接続に失敗しました
COOLIFY_TIMEOUT	リクエストがタイムアウトしました
COOLIFY_CONFIRM_REQUIRED	緊急操作のプレビューです — 続行するには confirm: true を指定してください
COOLIFY_AMBIGUOUS_MATCH	複数のリソースが名前に一致しました — ランク付けされた一覧から UUID を選択してください
COOLIFY_CLOUD_FORBIDDEN	Cloud トークンまたはチーム権限の問題です（HTTP 403）
COOLIFY_CLOUD_UNSUPPORTED	Coolify Cloud ではこのエンドポイントを利用できません（HTTP 404）

一時的な障害（HTTP 429、5xx、ネットワークエラー）が発生した場合、エラーをエージェントに返す前に、指数バックオフ（1s → 2s → 4s）を使って最大3回まで自動的に再試行します。

---

💬 エージェントのワークフロー例

「Coolify に接続できますか？ また、何が用意されていますか？」

system({ action: "verify" })
system({ action: "infrastructure_overview" })
resource({ action: "list" })

「nginx アプリを見つけてデプロイし、その後ログを表示してください。」

resource({ action: "find", query: "nginx" })
application({ action: "deploy", uuid: "<uuid>", wait: false })
deployment({ action: "watch", deployment_uuid: "<deployment_uuid>", timeout: 300 })
application({ action: "logs", uuid: "<uuid>" })

「フリート全体で何かおかしい気がします。」

diagnose({ action: "scan" })
diagnose({ action: "app", uuid: "<suspect>" })
diagnose({ action: "server", uuid: "<server>" })

「緊急です。まず影響範囲を確認してから、すべてを停止してください。」

emergency({ action: "stop_all" })                 // preview — would_affect, no mutation
emergency({ action: "stop_all", confirm: true })  // execute

「マルチインスタンス：登録済みのインスタンスを一覧表示し、それぞれを検証してください。」

instance({ action: "list" })
system({ action: "verify" })

---

✅ 現在のステータス

パッケージ 1.1.4 には、Coolify API 4.1.x 用の19個のツールと6つの MCP プロンプトが含まれています。

機能	状況
接続確認とインフラストラクチャの概要	✅ 提供済み
検索：resource.list / resource.find	✅ 提供済み
診断：アプリ、サーバー、全フリートのスキャンと追加のヒント	✅ 提供済み
Log Brain（diagnose.analyze）とプレイブック（incident、rollback、maintenance-window）	✅ 提供済み
デプロイのライフサイクル：開始／停止／再起動、待機モードと強制再ビルドを指定したデプロイ	✅ 提供済み
デプロイの追跡：一覧表示／取得／キャンセル	✅ 提供済み
デプロイの監視と範囲を限定したビルドログ	✅ 提供済み
アプリケーションのランタイムログ、範囲を限定した追跡、diagnose.logs	✅ 提供済み
インスタンス分析機能（intelligence.scorecard、graph、impact、janitor、cleanup）	✅ 提供済み
ドリフトと修復（manifest.audit、application.envs:promote / env.promote）	✅ 提供済み
デプロイガード（deployment.preflight、deployment.rollback）	✅ 提供済み
アプリケーション、サービス、データベースの CRUD	✅ 提供済み
動的なワンクリックのタイプ検出、レシピ、recipe.recommend	✅ 提供済み
セットアップウィザードと4つの IDE ワークフロースキル	✅ 提供済み
緊急オペレーション：停止、プロジェクトの再デプロイ／再起動、確認ゲートを通過後に実行	✅ 提供済み
PEM のマスキングを備えた SSH キーの CRUD（private_key）	✅ 提供済み
サーバーの CRUD と検証（server）	✅ 提供済み
プロジェクトと環境の CRUD（project、environment）	✅ 提供済み
明示的な reveal オプトインによるシークレットのマスキング	✅ 提供済み
構造化エラー、復旧のヒント、自動リトライ	✅ 提供済み
npm 配布と15以上のクライアント向けインストール設定ツール	✅ 提供済み
マルチインスタンスレジストリ（instance、instances.json）	✅ 提供済み
Coolify Cloud 対応（cloud-info、チームスコープのトークン）	✅ 提供済み
ローカルマニフェスト同期（.coolify/manifest.json、自動フック）	✅ 提供済み
ライブ UAT ハーネス（npm run uat:live）	✅ 提供済み
system.version による機能検出	✅ 提供済み
deployment.logs によるデプロイのビルドログ	✅ 提供済み

機能検出とビルドログ： system({ action: "version" }) は coolifyVersion（従来の version フィールドに代わるもの）、mcpVersion、Coolify 4.1.2 の機能フラグを示す capabilities マップを返します。アプリのトリアージと範囲を限定したランタイムログの末尾取得を1回の呼び出しで行うには、diagnose({ action: "logs", mode: "full", uuid: "..." }) を使用し、capabilities.diagnose_logs を確認してください。Log Brain によるパターンのトリアージには、diagnose({ action: "analyze", uuid: "..." }) を使用し、capabilities.diagnose_analyze を確認してください。ライブカタログに基づく推奨スタックには、recipe({ action: "recommend", stack: "..." }) を使用し、capabilities.recipe_recommend を確認してください。インスタンスの健全性、依存関係グラフ、影響、ジャニター／クリーンアップには、intelligence({ action: "scorecard" | "graph" | "impact" | "janitor" | "cleanup", ... }) を使用し、capabilities.intelligence_scorecard（および関連する intelligence_* キー）を確認してください。cleanup には confirm: true が必要です。マニフェストのドリフト監査とアプリ間の環境変数プロモートには、manifest({ action: "audit" }) と application({ action: "envs:promote", source_uuid, target_uuid, ... }) を使用し、capabilities.manifest_audit と capabilities.envs_promote を確認してください（既存の読み取り／環境変数 CRUD を組み合わせた MCP 機能であり、Coolify ネイティブの REST エンドポイントではありません）。デプロイのビルドログには、deployment({ action: "logs", deployment_uuid: "..." }) を優先して使用してください（または application_uuid を指定すると最新のデプロイを解決します）。互換性維持のため、deployment_uuid を指定した application.logs の経路も引き続き使用できます。ランタイムログの追跡には、application({ action: "logs", uuid: "...", follow: true }) を使用してください。アイドル状態またはタイムアウトになるまで、範囲を限定して MCP がポーリングします。system.version で capabilities.application_logs_follow を確認してください。

警告

Coolify 4.1.x は、安定したサービスまたはデータベースのログエンドポイントを公開していません。そのため、このサーバーはサービス／データベースのログアクションを提供・登録していません。互換性のある上流 API が利用可能になるまでは、アプリケーションのランタイムログとデプロイのビルドログを使用してください。

---

🔮 近日公開予定

今後の作業は、検証可能な上流プロジェクトおよびリポジトリの制約内で行います。

• 互換性のある Coolify API が安定して利用可能になったら、サービス／データベースのログを追加します。
• 有用なエージェントのワークフローにつながる場合は、docs/COVERAGE.md に記載された REST マッピングの未対応項目を解消します。
• インスタンス間のファンアウトについては、レート制限と認証情報の分離が明確に保証される場合にのみ、再検討します。

これらの範囲について、リリース日や互換性を保証するものではありません。具体的なリクエストには GitHub Issues をご利用ください。

---

🛠️ ローカル開発

git clone https://github.com/clezcoding/awesome-coolify.git
cd awesome-coolify
pnpm install
pnpm run build    # tsup → dist/
pnpm test         # vitest
pnpm run dev      # watch mode

ログは stderr にのみ出力されます。stdout は MCP プロトコル専用です。

メンテナー向けの公開フロー（build → pack --dry-run → publish）は、CONTRIBUTING.md に記載されています。

メモ

メンテナーは npm run uat:live を実行して、実際の Coolify インスタンスでライブ UAT を行えます。前提条件とレポートの出力については、CONTRIBUTING.md — ライブ UAT ハーネス を参照してください。ここに手順を重複して記載しないでください。

---

🔗 リンク

リソース	URL
インストール設定ツール	clezcoding.github.io/awesome-coolify/install.html
インストール用ランディングページ	clezcoding.github.io/awesome-coolify/
MCP JSON の例	docs/mcp.example.json
ブランド素材	docs/assets/
Coolify	coolify.io
MCP 仕様	modelcontextprotocol.io
イシューと機能リクエスト	GitHub Issues
コントリビューション	CONTRIBUTING.md
変更履歴	CHANGELOG.md
セキュリティポリシー	SECURITY.md
ライセンス	MIT