Komodo MCP Server

MCP Komodo

Komodo DevOps プラットフォーム向けの MCP サーバーです。Cursor、Claude Code、Claude Desktop で自然言語を使って、サーバー、スタック、デプロイ、ビルドなどを管理できます。

特長

• Komodo DevOps API 全体を網羅する 14 カテゴリにわたる 63 個のツール
• 細かな制御が可能な 3 つのアクセス階層（read-only、read-execute、full）
• KOMODO_CATEGORIES によるカテゴリの絞り込みで、必要なツールだけを公開
• HTTP 依存関係ゼロ――軽量なネイティブ fetch クライアントを使用し、SDK は不要
• GHCR で linux/amd64 と linux/arm64 向けの Docker イメージを提供
• Streamable HTTP プロトコルを使用する HTTP トランスポート（MCP_TRANSPORT=http）経由の リモート MCP
• 完全な型安全性を備えた TypeScript/ESM

API 互換性

Komodo 1.19.5 向けに構築されています。

クイックスタート

npx でサーバーを直接実行します。

KOMODO_URL="https://komodo.example.com" \
KOMODO_API_KEY="your-api-key" \
KOMODO_API_SECRET="your-api-secret" \
npx -y @samik081/mcp-komodo

サーバーは起動時に Komodo への接続を検証します。認証情報が不足しているか無効な場合は、明確なエラーを表示して直ちに終了します。

Docker

Docker で実行します（stdio トランスポート、npx と同じです）。

docker run --rm -i \
  -e KOMODO_URL=https://komodo.example.com \
  -e KOMODO_API_KEY=your-api-key \
  -e KOMODO_API_SECRET=your-api-secret \
  ghcr.io/samik081/mcp-komodo

HTTP トランスポートを使ってリモート MCP サーバーとして実行するには、次のようにします。

docker run -d -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e KOMODO_URL=https://komodo.example.com \
  -e KOMODO_API_KEY=your-api-key \
  -e KOMODO_API_SECRET=your-api-secret \
  ghcr.io/samik081/mcp-komodo

MCP エンドポイントは http://localhost:3000、ヘルスチェックは http://localhost:3000/health で利用できます。

設定

Claude Code CLI（推奨）：

# Using npx
claude mcp add --transport stdio komodo \
  --env KOMODO_URL=https://komodo.example.com \
  --env KOMODO_API_KEY=your-api-key \
  --env KOMODO_API_SECRET=your-api-secret \
  -- npx -y @samik081/mcp-komodo

# Using Docker
claude mcp add --transport stdio komodo \
  --env KOMODO_URL=https://komodo.example.com \
  --env KOMODO_API_KEY=your-api-key \
  --env KOMODO_API_SECRET=your-api-secret \
  -- docker run --rm -i ghcr.io/samik081/mcp-komodo

# Using remote HTTP (connect to a running Docker container or HTTP server)
claude mcp add --transport http komodo http://localhost:3000

JSON 設定（Claude Code の .mcp.json、Claude Desktop の claude_desktop_config.json、Cursor の .cursor/mcp.json で動作します）：

{
  "mcpServers": {
    "komodo": {
      "command": "npx",
      "args": ["-y", "@samik081/mcp-komodo"],
      "env": {
        "KOMODO_URL": "https://komodo.example.com",
        "KOMODO_API_KEY": "your-api-key",
        "KOMODO_API_SECRET": "your-api-secret"
      }
    }
  }
}

Docker（stdio）：

{
  "mcpServers": {
    "komodo": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
        "-e", "KOMODO_URL=https://komodo.example.com",
        "-e", "KOMODO_API_KEY=your-api-key",
        "-e", "KOMODO_API_SECRET=your-api-secret",
        "ghcr.io/samik081/mcp-komodo"
      ]
    }
  }
}

リモート MCP（実行中の Docker コンテナまたは HTTP サーバーに接続）：

{
  "mcpServers": {
    "komodo": {
      "type": "streamable-http",
      "url": "http://localhost:3000"
    }
  }
}

アクセス階層

KOMODO_ACCESS_TIER 環境変数を使って、利用可能なツールを制御します。

階層	ツール	説明
full（デフォルト）	63	読み取り、実行、書き込み――すべてを操作できます
read-execute	55	読み取りと実行――リソースの作成・削除、ユーザー管理はできません
read-only	39	読み取り専用――状態を変更せずに調査できます

階層の詳細：

• full：63 個すべてのツールを利用できます。Komodo リソースの作成、更新、削除を行う komodo_write_resource と、ユーザー管理ツール（サービスユーザー、API キー、権限）が含まれます。
• read-execute：55 個のツールを利用できます。すべての読み取りツールに加え、実行ツール（デプロイ、プル、ライフサイクル、実行など）を利用できます。komodo_write_resource とユーザー管理の書き込みツールは非表示になります。
• read-only：39 個のツールを利用できます。リスト、取得、ログ、検査、統計、概要、操作履歴、ユーザーと権限の読み取りのみです。実行ツールと書き込みツールはすべて非表示になります。

選択した階層で利用できないツールは MCP サーバーに登録されません。AI ツールのツール一覧にも表示されないため、コンテキストをすっきり保てます。

KOMODO_ACCESS_TIER に read-only、read-execute、または full（デフォルト：full）を設定します。

環境変数

変数	必須	デフォルト	説明
KOMODO_URL	はい	--	Komodo Core インスタンスの URL
KOMODO_API_KEY	はい	--	認証用の API キー
KOMODO_API_SECRET	はい	--	認証用の API シークレット
KOMODO_ACCESS_TIER	いいえ	full	アクセス階層：read-only、read-execute、full
KOMODO_CATEGORIES	いいえ	(すべて)	カンマ区切りのカテゴリ許可リスト（例：servers,stacks,builds）
KOMODO_TOOL_BLACKLIST	いいえ	(なし)	除外するツール名のカンマ区切りリスト（例：komodo_destroy_stack）
KOMODO_TOOL_WHITELIST	いいえ	(なし)	アクセス階層とカテゴリのフィルターを無視して、必ず含めるツール名のカンマ区切りリスト
KOMODO_ALLOW_ENV_VALUES	いいえ	(階層による)	show_env_values: true によって、インスペクションツールが環境変数の値を平文で返せるようにするかどうか。デフォルトでは read-execute／full で許可され、read-only では拒否されます。上書きするには true または false を設定します
DEBUG	いいえ	false	デバッグログを stderr に出力します
MCP_TRANSPORT	いいえ	stdio	トランスポートモード：stdio（デフォルト）または http
MCP_PORT	いいえ	3000	HTTP サーバーのポート（MCP_TRANSPORT=http の場合のみ使用）
MCP_HOST	いいえ	0.0.0.0	HTTP サーバーのバインドアドレス（MCP_TRANSPORT=http の場合のみ使用）
MCP_SESSION_IDLE_TIMEOUT	いいえ	1800	HTTP セッションが閉じられ、メモリが解放されるまでの非アクティブ時間（秒）。SSE ストリームに接続されているセッションは閉じられません。0 にすると無効になります。MCP_TRANSPORT=http の場合のみ使用されます
MCP_EXCLUDE_TOOL_TITLES	いいえ	false	true に設定すると、登録時にツールのタイトルを省略します（トークンを節約できます）

Komodo UI の Settings > API Keys から API キーを生成します。

利用可能なカテゴリ

servers、stacks、deployments、containers、builds、repos、procedures、actions、builders、alerters、resource-syncs、updates、users、write

ツール

mcp-komodo には、カテゴリ別に整理された 63 個のツールがあります。各ツールの「アクセス」列には必要な最低階層が表示されます：read-only（すべての階層で利用可能）、read-execute（read-execute または full が必要）、full（full 階層のみ必要）。「ヒント」列にはツールの動作が表示されます：read-only（状態を変更しない）、destructive（既存の状態を変更する）、idempotent（2 回呼び出しても同じ結果）。

すべての 16 個の実行ツールは、デフォルトで操作の完了を待ち、実際の結果を報告します。待機せずに実行するには wait: false を渡し、待機時間を制限するには wait_timeout_seconds を指定します（デフォルトは 45 秒）。

サーバー（10 個のツール）

| ツール | 説明 | アクセス | ヒント | |------|-------------|--------|-------| | `komodo_list_servers` | ステータスとリージョンを含むすべてのサーバーを一覧表示します | 読み取り専用 | 読み取り専用、冪等 | | `komodo_get_server` | サーバーの設定、ステータス、アクション状態を取得します | 読み取り専用 | 読み取り専用、冪等 | | `komodo_get_server_stats` | CPU、メモリ、ディスク使用量、ロードアベレージを取得します | 読み取り専用 | 読み取り専用、冪等 | | `komodo_get_server_info` | OS の詳細、ハードウェア情報、実行中のプロセスを取得します | 読み取り専用 | 読み取り専用、冪等 | | `komodo_inspect_docker_container` | Docker コンテナを検査します（`docker inspect` のペイロード）。`show_env_values: true` を指定しない限り、環境変数の値は `sha256:<12-hex>` ダイジェストとして表示されます（`KOMODO_ALLOW_ENV_VALUES=true` が設定されていない場合、`read-only` ティアでは拒否されます）。リダクションの対象は `Env` 配列のみのため、ラベル、cmd、マウントはリダクションされずに返されます | 読み取り専用 | 読み取り専用、冪等 | | `komodo_inspect_docker_image` | Docker イメージを検査します（`docker image inspect` のペイロード）。`show_env_values: true` を指定しない限り、イメージに組み込まれた環境変数の値は `sha256:<12-hex>` ダイジェストとして表示されます（`KOMODO_ALLOW_ENV_VALUES=true` が設定されていない場合、`read-only` ティアでは拒否されます）。リダクションの対象は `Env` 配列のみのため、ラベル、cmd、レイヤーはリダクションされずに返されます | 読み取り専用 | 読み取り専用、冪等 | | `komodo_inspect_docker_network` | Docker ネットワークを検査します（`docker network inspect` と同等） | 読み取り専用 | 読み取り専用、冪等 | | `komodo_inspect_docker_volume` | Docker ボリュームを検査します（`docker volume inspect` と同等） | 読み取り専用 | 読み取り専用、冪等 | | `komodo_prune_docker` | サーバー上の未使用の Docker リソースをプルーニングします | 読み取り・実行 | 破壊的、冪等 | | `komodo_delete_docker_resource` | 指定した Docker イメージ、ボリューム、またはネットワークを削除します | 読み取り・実行 | 破壊的 |

スタック（10 ツール）

ツール	説明	アクセス	ヒント
komodo_list_stacks	状態、サーバー、サービス数を含むすべてのスタックを一覧表示します	読み取り専用	読み取り専用、冪等
komodo_get_stack	スタックの設定、サービス、アクション状態を取得します	読み取り専用	読み取り専用、冪等
komodo_list_stack_services	イメージ、コンテナの状態、更新の有無を含むスタック内のサービスを一覧表示します	読み取り専用	読み取り専用、冪等
komodo_get_stacks_summary	状態別に集計した、すべてのスタックの件数を取得します	読み取り専用	読み取り専用、冪等
komodo_get_stack_log	スタックサービスのログを取得します。検索条件は任意です	読み取り専用	読み取り専用、冪等
komodo_inspect_stack_container	スタック内の特定のサービスのコンテナを検査します（docker inspect のペイロード）。show_env_values: true を指定しない限り、環境変数の値は sha256:<12-hex> ダイジェストとして表示されます（KOMODO_ALLOW_ENV_VALUES=true が設定されていない場合、read-only ティアでは拒否されます）。リダクションの対象は Env 配列のみのため、ラベル、cmd、マウントはリダクションされずに返されます	読み取り専用	読み取り専用、冪等
komodo_deploy_stack	スタックをデプロイまたは再デプロイします	読み取り・実行	破壊的
komodo_pull_stack	再デプロイせずに最新のイメージをプルします（docker compose pull）	読み取り・実行	冪等
komodo_stack_lifecycle	スタックを起動、停止、再起動、一時停止、または一時停止解除します。特定のサービスを対象にすることもできます	読み取り・実行	破壊的
komodo_destroy_stack	スタックを完全に破棄します	読み取り・実行	破壊的

デプロイメント（9 ツール）

| ツール | 説明 | アクセス | ヒント | |------|-------------|--------|-------| | `komodo_list_deployments` | 状態、イメージ、サーバーを含むすべてのデプロイメントを一覧表示します | 読み取り専用 | 読み取り専用、冪等 | | `komodo_get_deployment` | デプロイメントの設定、コンテナの状態、アクションの状態を取得します | 読み取り専用 | 読み取り専用、冪等 | | `komodo_get_deployments_summary` | すべてのデプロイメントの状態別の合計数を取得します | 読み取り専用 | 読み取り専用、冪等 | | `komodo_get_deployment_log` | コンテナのログを取得します。検索は任意です | 読み取り専用 | 読み取り専用、冪等 | | `komodo_inspect_deployment_container` | デプロイメントのコンテナを検査します（`docker inspect` のペイロード）。`show_env_values: true` を指定しない限り、環境変数の値は `sha256:<12-hex>` ダイジェストとして表示されます（`read-only` ティアでは拒否されます。ただし、`KOMODO_ALLOW_ENV_VALUES=true` の場合を除きます）。秘匿化の対象は `Env` 配列のみのため、ラベル、cmd、マウントは秘匿化されずに返されます | 読み取り専用 | 読み取り専用、冪等 | | `komodo_deploy_deployment` | 最新のイメージと設定でデプロイします | 読み取り・実行 | 破壊的 | | `komodo_pull_deployment` | 再デプロイせずに最新のイメージを取得します（docker pull） | 読み取り・実行 | 冪等 | | `komodo_deployment_lifecycle` | デプロイメントを開始、停止、再起動、一時停止、または一時停止解除します | 読み取り・実行 | 破壊的 | | `komodo_destroy_deployment` | デプロイメントを完全に破棄します | 読み取り・実行 | 破壊的 |

コンテナ（1 ツール）

ツール	説明	アクセス	ヒント
komodo_get_container_log	サーバー上の任意の Docker コンテナからログを取得します	読み取り専用	読み取り専用、冪等

ビルド（4 ツール）

ツール	説明	アクセス	ヒント
komodo_list_builds	バージョン情報を含むすべてのビルド設定を一覧表示します	読み取り専用	読み取り専用、冪等
komodo_get_build	ビルド設定、ビルダー、アクションの状態を取得します	読み取り専用	読み取り専用、冪等
komodo_run_build	Docker イメージを作成するためにビルドを実行します	読み取り・実行	—
komodo_cancel_build	実行中のビルドをキャンセルします	読み取り・実行	破壊的、冪等

リポジトリ（3 ツール）

ツール	説明	アクセス	ヒント
komodo_list_repos	URL、サーバー、状態を含むすべてのリポジトリを一覧表示します	読み取り専用	読み取り専用、冪等
komodo_get_repo	リポジトリの設定、ブランチ、アクションの状態を取得します	読み取り専用	読み取り専用、冪等
komodo_repo_clone_pull	対象サーバー上でリポジトリをクローンまたはプルします	読み取り・実行	破壊的

プロシージャ（3 ツール）

ツール	説明	アクセス	ヒント
komodo_list_procedures	状態を含むすべてのプロシージャを一覧表示します	読み取り専用	読み取り専用、冪等
komodo_get_procedure	プロシージャのステージ、操作、アクションの状態を取得します	読み取り専用	読み取り専用、冪等
komodo_run_procedure	プロシージャを実行します（すべてのステージを実行します）	読み取り・実行	破壊的

アクション（3 ツール）

ツール	説明	アクセス	ヒント
komodo_list_actions	状態を含むすべてのアクションを一覧表示します	読み取り専用	読み取り専用、冪等
komodo_get_action	アクション設定とアクションの状態を取得します	読み取り専用	読み取り専用、冪等
komodo_run_action	カスタムの TypeScript/Deno アクションを実行します	読み取り・実行	破壊的

ビルダー（2 ツール）

ツール	説明	アクセス	ヒント
komodo_list_builders	タイプを含むすべてのビルダーを一覧表示します	読み取り専用	読み取り専用、冪等
komodo_get_builder	ビルダーのタイプ、サーバー設定、状態を取得します	読み取り専用	読み取り専用、冪等

通知設定（2 ツール）

| ツール | 説明 | アクセス | ヒント | |------|-------------|--------|-------| | `komodo_list_alerters` | タイプとともにすべてのアラート通知先を一覧表示します | 読み取り専用 | 読み取り専用、冪等 | | `komodo_get_alerter` | アラート通知先のエンドポイントタイプ、設定、ステータスを取得します | 読み取り専用 | 読み取り専用、冪等 |

リソース同期（3 ツール）

ツール	説明	アクセス	ヒント
komodo_list_resource_syncs	状態とリポジトリ情報とともに、すべてのリソース同期を一覧表示します	読み取り専用	読み取り専用、冪等
komodo_get_resource_sync	同期設定、管理対象リソース、状態を取得します	読み取り専用	読み取り専用、冪等
komodo_trigger_sync	Git リポジトリから GitOps 同期を実行します	読み取り・実行	破壊的

更新（2 ツール）

ツール	説明	アクセス	ヒント
komodo_list_updates	リソースタイプ、ターゲット、操作、成功のフィルターを使って操作履歴を一覧表示します	読み取り専用	読み取り専用、冪等
komodo_get_update	各ステージの標準出力／標準エラーを含むログなど、操作の詳細全体を取得します	読み取り専用	読み取り専用、冪等

ユーザー（10 ツール）

ユーザーツールは 10 個すべて、Komodo 管理者アカウントが必要です。Komodo は、設定されたアクセス階層にかかわらず、管理者以外の API キーによるこれらの操作を拒否します。

ツール	説明	アクセス	ヒント
komodo_list_users	Komodo ユーザーを一覧表示します。サービスユーザーで絞り込むこともできます	読み取り専用	読み取り専用、冪等
komodo_list_api_keys_for_service_user	サービスユーザーの API キーを一覧表示します（シークレットは返されません）	読み取り専用	読み取り専用、冪等
komodo_list_permissions	ユーザーまたはユーザーグループに付与された権限を一覧表示します	読み取り専用	読み取り専用、冪等
komodo_create_service_user	自動化用のサービスユーザーを作成します	フル	—
komodo_delete_user	ID またはユーザー名でユーザーを削除します	フル	破壊的
komodo_create_api_key_for_service_user	サービスユーザーの API キーを作成します（シークレットは一度だけ返されます）	フル	—
komodo_delete_api_key_for_service_user	サービスユーザーの API キーを削除します	フル	破壊的
komodo_update_user_base_permissions	ユーザーの enabled / create-servers / create-builds フラグを更新します	フル	破壊的、冪等
komodo_update_permission_on_resource_type	あるタイプのすべてのリソースに対するユーザーまたはグループの基本権限を設定します	フル	破壊的、冪等
komodo_update_permission_on_target	特定の 1 つのリソースに対するユーザーまたはグループの権限を設定します	フル	破壊的、冪等

書き込み（1 ツール）

ツール	説明	アクセス	ヒント
komodo_write_resource	任意の Komodo リソースを作成、更新、または削除します	フル	破壊的

動作確認

MCP クライアントを設定したら、AI アシスタントに次のように尋ねてください。

「Komodo に接続されているサーバーは何ですか？」

接続が機能している場合、アシスタントは komodo_list_servers を呼び出し、現在の状態とリージョンを含むサーバー一覧を返します。

使用例

設定後は、AI ツールに自然な言葉で質問できます。

• 「すべてのサーバーとそのステータスを一覧表示して」 -- komodo_list_servers を呼び出し、各サーバーの現在の状態とリージョンを表示します。

• 「サーバー prod-01 の CPU とメモリの使用状況は？」 -- komodo_get_server_stats を呼び出し、リアルタイムのリソース使用状況を表示します。

• 「本番スタックのログを表示して」 -- komodo_get_stack_log を呼び出し、スタック内のすべてのサービスから最近のログ出力を取得します。

• 「フロントエンドスタックをデプロイして」 -- komodo_deploy_stack を呼び出し、現在の設定でスタックを再デプロイします。

• 「フロントエンドスタックのデプロイが失敗したのはなぜ？」 -- komodo_list_updates を呼び出して失敗したデプロイを見つけ、次に komodo_get_update を呼び出して stdout/stderr を含む完全なログを表示します。

• 「監視スタックの最新イメージをプルして」 -- komodo_pull_stack を呼び出し、再デプロイせずに更新されたイメージをダウンロードします。

• 「myapp:latest のイメージを使用して、api-staging という名前の新しいデプロイメントを作成して」 -- komodo_write_resource を呼び出し、Komodo に新しい Deployment リソースを作成します。

トラブルシューティング

接続が拒否される

KOMODO_URL が正しいことと、MCP サーバーの実行環境から Komodo Core に接続できることを確認してください。サーバーは起動時に接続を検証するため、正常に起動した場合、その時点では URL は有効でした。

認証情報が無効／401 Unauthorized

API キーとシークレットが正しいことを確認してください。Komodo UI の Settings > API Keys で、キーが取り消されていないこと、また有効期限が切れていないことを確認してください。

ツールが表示されない

アクセスティアの設定を確認してください。read-only モードでは、39 個のツールのみが登録されます。read-execute モードでは、55 個のツールが登録されます。すべての 63 個のツールを使用するには、full を指定するか、KOMODO_ACCESS_TIER を省略してください。KOMODO_CATEGORIES を確認してください。リストにあるカテゴリのツールのみが登録されます。また、stderr の出力を確認し、サーバーがエラーなしで起動したことを確認してください。

開発

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode (auto-reload)
npm run dev

# Open the MCP Inspector for interactive testing
npm run inspect

ライセンス

MIT