docker-mcp

Docker MCP Server

Cursor、Claude Desktop、その他の MCP 対応クライアントなどの AI アシスタントが、自然言語でのやり取りを通じて Docker コンテナ、イメージ、ネットワーク、ボリューム、レジストリをシームレスに管理できるようにする、包括的な Model Context Protocol（MCP）サーバーです。

Docker MCP Server を選ぶ理由

• 設定不要 - npx ですぐに使え、インストールも不要です
• 安全性を最優先 - 破壊的な操作には2段階の確認を設けています
• クロスプラットフォーム - Docker ソケットを自動検出し、Windows、Linux、macOS で動作します
• 包括的 - Compose、レジストリ、システム操作を含む、Docker API の全機能を網羅しています
• AI ネイティブ - AI アシスタント向けに設計されており、明確で構造化された応答を提供します

機能

コンテナ管理

• ライフサイクル全体を制御：コンテナの作成、起動、停止、再起動、強制終了、削除
• 監視：リアルタイムのログ、統計情報、コンテナの検査
• 高度な操作：一時停止と再開、コマンドの実行、リソース管理

イメージ管理

• レジストリ操作：イメージの取得、プッシュ、タグ付け、削除
• ビルドのサポート：完全な設定を指定して Dockerfile からイメージをビルド
• 検査：イメージの履歴、レイヤー、メタデータの詳細を確認

ネットワーク管理

• ネットワーク操作：Docker ネットワークの作成、削除、検査
• コンテナ接続：コンテナをネットワークに接続、または切断
• ネットワーク検出：高度なオプションを使ってネットワークを一覧表示し、フィルタリング

ボリューム管理

• ボリューム操作：ボリュームの作成、削除、検査
• データの永続化：コンテナ用の永続ストレージを管理
• ボリュームの検査：ボリューム情報とマウントポイントの詳細を確認

システム操作

• システム情報：Docker デーモンの情報、バージョン、機能
• リソースのクリーンアップ：未使用のイメージ、コンテナ、ボリューム、ネットワークを整理
• イベントの監視：リアルタイムの Docker イベントストリーム

コンテナ内でのコマンド実行

• コマンドの実行：実行中のコンテナ内でコマンドを実行
• 対話型セッション：exec インスタンスを作成、管理
• 出力のストリーミング：コマンドの出力とログをリアルタイムで表示

レジストリ連携

• Docker Hub：リポジトリの検索、タグの一覧表示、認証、イメージの取得とプッシュ
• GitHub Container Registry（GHCR）：完全な認証とイメージ管理
• マルチレジストリ対応：複数のレジストリをシームレスに利用

Docker Compose のサポート

• 複数コンテナの管理：Compose サービスの起動、停止、再起動
• サービスの監視：Compose サービスのログとステータスを表示
• ビルド操作：依存関係を管理しながら Compose サービスをビルド
• 設定の検証：docker-compose.yml ファイルを解析し、検証

安全機能

• すべての破壊的な操作で2段階の確認
• リソースのプレビュー：確認前に削除対象を表示
• 2種類の確認方法：
  • Confirm パラメーター（デフォルト）：どこでも使える、シンプルで信頼性の高い方法
  • MCP Elicitation API（高度な方法）：UX を向上させる、フォームを使った対話型の確認

インストール

npx を使用する場合（推奨）

npx @alisaitteke/docker-mcp

ローカルインストール

npm install -g @alisaitteke/docker-mcp

または、プロジェクトにローカルインストールします。

npm install @alisaitteke/docker-mcp

クイックスタート

Cursor を使用する場合

1. Cursor の MCP 設定に追加します（通常は .cursor/mcp.json などにあります）。

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["@alisaitteke/docker-mcp"]
    }
  }
}

2. Cursor を再起動して、AI で Docker の管理を始めましょう！

Claude Desktop を使用する場合

1. Claude Desktop の設定に追加します。
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["@alisaitteke/docker-mcp"]
    }
  }
}

2. Claude Desktop を再起動して、AI で Docker の管理を始めましょう！

ローカルでの開発とテスト

前提条件

• Node.js 18.0.0 以降
• Docker デーモンが実行中であること
• npm または yarn

セットアップ

1. リポジトリをクローンします。

git clone <repository-url>
cd docker-mcp

2. 依存関係をインストールします。

npm install

3. プロジェクトをビルドします。

npm run build

ローカルでの実行

方法 1：npm start を使用する（ビルド後）

# Build first
npm run build

# Run the server
npm start

方法 2：npm run dev を使用する（tsx による開発モード）

npm run dev

ビルドせずに TypeScript を直接実行するために、tsx を使用します。

方法 3：直接実行

# Build first
npm run build

# Run directly with node
node dist/index.js

方法 4：バイナリを使用する

# Build first
npm run build

# Make sure the binary is executable
chmod +x bin/docker-mcp-server.js

# Run the binary
./bin/docker-mcp-server.js

開発ワークフロー

1. src/ 内のソースファイルを変更します
2. プロジェクトをビルドします。

npm run build

3. 変更をテストします。

npm start
# or
npm run dev

4. TypeScript のエラーを確認します。

npm run typecheck

5. コードをリントします。

npm run lint

トラブルシューティング

Docker の接続に関する問題：

• Docker デーモンが実行中であることを確認します：docker ps
• Linux/macOS：Docker ソケットの権限を確認します：ls -la /var/run/docker.sock
• Windows：Docker Desktop が実行中で、名前付きパイプにアクセスできることを確認します
• リモート Docker の場合は、環境変数を設定します：DOCKER_HOST、DOCKER_CERT_PATH など
• macOS：/var/run/docker.sock が存在しない場合は、~/.docker/run/docker.sock を試してください（Docker Desktop 4.0 以降）

ビルドエラー：

• node_modules を削除して再インストールします：rm -rf node_modules && npm install
• TypeScript のバージョンとの互換性を確認します
• すべての依存関係がインストールされていることを確認します：npm install

実行時エラー：

• Docker にアクセスできることを確認します：docker version
• ビルドが成功したことを確認します：ls -la dist/
• サーバーのログを確認します（エラーは stderr に出力されます）

設定

サーバーはオペレーティングシステムを自動検出し、適切な Docker ソケットパスを使用します。

プラットフォーム別のデフォルト設定

• Linux：/var/run/docker.sock（Unix ソケット）
• macOS：/var/run/docker.sock または ~/.docker/run/docker.sock（Docker Desktop 4.0 以降）
• Windows：//./pipe/docker_engine（名前付きパイプ）

接続方法（優先順位順）

1. 環境変数（最優先）：

   • DOCKER_HOST - Docker デーモンのホスト（例：tcp://localhost:2376、npipe:////./pipe/docker_engine）
   • DOCKER_PORT - Docker デーモンのポート
   • DOCKER_PROTOCOL - プロトコル（http または https）
   • DOCKER_SOCKET_PATH - Docker ソケットのパス（プラットフォームのデフォルトを上書きします）
   • DOCKER_CERT_PATH - Docker 証明書ディレクトリのパス
   • DOCKER_TLS_VERIFY - TLS 検証を有効にするかどうか（1 または 0）

2. プラットフォーム別のデフォルト設定（自動検出）：

   • Linux：/var/run/docker.sock
   • macOS：/var/run/docker.sock（利用可能な場合は ~/.docker/run/docker.sock）
   • Windows：//./pipe/docker_engine

Windows の設定

Windows では、Docker Desktop は名前付きパイプを使用します。サーバーは Windows を自動検出し、適切なパスを使用します。次のように明示的に設定することもできます。

# Using environment variable
set DOCKER_SOCKET_PATH=//./pipe/docker_engine

# Or using DOCKER_HOST
set DOCKER_HOST=npipe:////./pipe/docker_engine

リモート Docker ホスト

リモート Docker ホストに接続するには、次のようにします。

# Linux/macOS
export DOCKER_HOST=tcp://192.168.1.100:2376
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=/path/to/certs

# Windows
set DOCKER_HOST=tcp://192.168.1.100:2376
set DOCKER_TLS_VERIFY=1
set DOCKER_CERT_PATH=C:\path\to\certs

利用可能なツール

コンテナツール

• docker_list_containers - すべてのコンテナを一覧表示
• docker_create_container - 新しいコンテナを作成
• docker_start_container - コンテナを起動
• docker_stop_container - コンテナを停止
• docker_restart_container - コンテナを再起動
• docker_kill_container - コンテナを強制終了
• docker_remove_container - コンテナを削除
• docker_inspect_container - コンテナの詳細を取得
• docker_container_logs - コンテナのログを取得
• docker_container_stats - コンテナの統計情報を取得
• docker_pause_container - コンテナを一時停止
• docker_unpause_container - コンテナの一時停止を解除

イメージツール

• docker_list_images - すべてのイメージを一覧表示
• docker_pull_image - レジストリからイメージを取得
• docker_push_image - レジストリにイメージをプッシュ
• docker_tag_image - イメージにタグを付ける
• docker_remove_image - イメージを削除
• docker_inspect_image - イメージの詳細を取得
• docker_image_history - イメージの履歴を取得

ネットワークツール

• docker_list_networks - すべてのネットワークを一覧表示
• docker_create_network - ネットワークを作成
• docker_remove_network - ネットワークを削除
• docker_inspect_network - ネットワークの詳細を取得
• docker_connect_container - コンテナをネットワークに接続
• docker_disconnect_container - コンテナをネットワークから切断

ボリュームツール

• docker_list_volumes - すべてのボリュームを一覧表示
• docker_create_volume - ボリュームを作成
• docker_remove_volume - ボリュームを削除
• docker_inspect_volume - ボリュームの詳細を取得

システムツール

• docker_system_info - Docker システム情報を取得
• docker_version - Docker のバージョンを取得
• docker_prune_system - 使用されていないリソースをすべて削除
• docker_prune_images - 使用されていないイメージを削除
• docker_prune_containers - 停止中のコンテナを削除
• docker_prune_volumes - 使用されていないボリュームを削除
• docker_prune_networks - 使用されていないネットワークを削除

実行ツール

• docker_exec - コンテナ内でコマンドを実行
• docker_inspect_exec - 実行インスタンスの詳細を取得

Compose ツール

• docker_compose_up - Docker Compose サービスを起動
• docker_compose_down - Docker Compose サービスを停止して削除
• docker_compose_ps - Docker Compose サービスを一覧表示
• docker_compose_logs - Docker Compose サービスの出力を表示
• docker_compose_config - docker-compose.yml ファイルを解析して検証
• docker_compose_build - Docker Compose サービスをビルド
• docker_compose_restart - Docker Compose サービスを再起動
• docker_compose_stop - Docker Compose サービスを停止
• docker_compose_start - Docker Compose サービスを起動

レジストリツール

• dockerhub_search - Docker Hub を検索
• dockerhub_get_tags - Docker Hub からリポジトリのタグを取得
• dockerhub_authenticate - Docker Hub で認証
• dockerhub_pull - Docker Hub から取得
• dockerhub_push - Docker Hub にプッシュ
• ghcr_authenticate - GitHub Container Registry で認証
• ghcr_pull - GHCR から取得
• ghcr_push - GHCR にプッシュ

使用例

実行中のコンテナを一覧表示

{
  "name": "docker_list_containers",
  "arguments": {
    "all": false
  }
}

コンテナを作成して起動

{
  "name": "docker_create_container",
  "arguments": {
    "image": "nginx:latest",
    "name": "my-nginx",
    "ports": {"80/tcp": {}}
  }
}

次に、起動します：

{
  "name": "docker_start_container",
  "arguments": {
    "id": "my-nginx"
  }
}

Docker Hub からイメージを取得

{
  "name": "docker_pull_image",
  "arguments": {
    "name": "ubuntu:20.04"
  }
}

Docker Hub を検索

{
  "name": "dockerhub_search",
  "arguments": {
    "query": "node",
    "limit": 10
  }
}

コンテナ内でコマンドを実行

{
  "name": "docker_exec",
  "arguments": {
    "containerId": "my-container",
    "cmd": ["ls", "-la"],
    "tty": false
  }
}

Docker Compose サービスを起動

{
  "name": "docker_compose_up",
  "arguments": {
    "projectDir": "/path/to/compose/project",
    "detach": true,
    "build": true
  }
}

Compose のログを表示

{
  "name": "docker_compose_logs",
  "arguments": {
    "projectDir": "/path/to/compose/project",
    "follow": false,
    "tail": 100
  }
}

確認してリソースを削除

破壊的な操作（削除、強制終了、プルーニング）では、次の 2 つの確認方法を利用できます。

方法 1：パラメーターによる確認（デフォルト — どこでも動作）

ステップ 1：プレビュー（confirm なし）

{
  "name": "docker_remove_volume",
  "arguments": {
    "name": "my-volume"
  }
}

ボリュームの詳細と警告メッセージが返されます。

ステップ 2：確認（confirm=true を指定）

{
  "name": "docker_remove_volume",
  "arguments": {
    "name": "my-volume",
    "confirm": true
  }
}

これにより、ボリュームが実際に削除されます。

方法 2：MCP Elicitation API（高度 — 優れた UX）

お使いの MCP クライアント（Cursor、Claude Desktop）が Elicitation API に対応している場合は、対話形式の確認を使用できます。

{
  "name": "docker_remove_volume",
  "arguments": {
    "name": "my-volume",
    "useElicitation": true
  }
}

対応している場合、クライアントに対話形式の確認ダイアログが表示されます。クライアントには確認を求めるフォームが表示され、ユーザーが承諾した場合にのみ操作が実行されます。

注： Elicitation API の対応状況は MCP クライアントによって異なります。クライアントが対応していない場合、サーバーは自動的に confirm パラメーター方式に切り替えます。

確認が必要な操作：

• docker_remove_volume — ボリュームの削除
• docker_remove_container — コンテナーの削除
• docker_kill_container — コンテナーの強制終了
• docker_remove_image — イメージの削除
• docker_remove_network — ネットワークの削除
• docker_prune_system — 未使用のリソースをすべてクリーンアップ
• docker_prune_images — 未使用のイメージをクリーンアップ
• docker_prune_containers — 停止中のコンテナーをクリーンアップ
• docker_prune_volumes — 未使用のボリュームをクリーンアップ
• docker_prune_networks — 未使用のネットワークをクリーンアップ

サーバーのテスト

クイックテスト

1. プロジェクトをビルドします。

npm run build

2. テストスクリプトを使用します。

./test-server.sh

または、手動でテストします。

3. Docker 接続をテストします。

# The server will exit with error if Docker is not accessible
node dist/index.js

Docker が実行中の場合は、次のように表示されます。

Docker MCP Server running on stdio

4. jq を使用して JSON を整形し、シンプルな MCP リクエストをテストします。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js | jq

注： サーバーは stdio 経由で通信するため、JSON-RPC リクエストを待機します。終了するには Ctrl+C を押してください。

手動テストの手順

1. サーバーを起動します。

npm run build
npm start

2. 別のターミナルで、curl を使用してテストする（HTTP トランスポートを使用する場合）か、MCP クライアントを使用します。

3. Docker 操作が動作することを確認します。

   • コンテナーを一覧表示する：docker_list_containers ツールを使用します
   • システム情報を確認する：docker_system_info ツールを使用します

統合テスト

統合テストを実施するには、MCP クライアントが必要です。サーバーは stdio（標準入力／出力）経由で通信するため、次のような MCP 対応クライアントで使用するように設計されています。

• Cursor IDE
• Claude Desktop
• カスタム MCP クライアント

デバッグ

stderr の出力を確認すると、詳細なログを有効にできます。サーバーはエラーとステータスメッセージを stderr に書き込みます。

# Run and capture stderr
node dist/index.js 2> debug.log

要件

• Node.js 18.0.0 以降
• Docker デーモンが実行中で、アクセス可能であること
• 対応プラットフォーム：
  • Linux（x64、ARM64）
  • macOS（Intel、Apple Silicon）
  • Windows（x64、ARM64）
• リモート Docker の場合：適切なネットワークアクセスと TLS 証明書（TLS を使用する場合）

プラットフォーム固有の注意事項

• Linux：/var/run/docker.sock に Unix ソケットを持つ Docker デーモンが必要です
• macOS：Docker Desktop で動作します。ソケットの場所は自動的に検出されます。
• Windows：Docker Desktop で動作します。名前付きパイプ //./pipe/docker_engine を使用します

クイックスタート（ローカル開発）

# Clone and setup
git clone <repository-url>
cd docker-mcp
npm install

# Build
npm run build

# Test
./test-server.sh

# Run
npm start
# or for development
npm run dev

ライセンス

MIT

MCP クライアントでのテスト

Cursor でのテスト（ローカル開発）

ローカルで開発していて、Cursor でテストする場合：

1. プロジェクトをビルドします。

npm run build

2. Cursor の MCP 設定（通常は .cursor/mcp.json など）に追加します。

{
  "mcpServers": {
    "docker": {
      "command": "node",
      "args": ["/absolute/path/to/docker-mcp/dist/index.js"]
    }
  }
}

バイナリを使用する場合：

{
  "mcpServers": {
    "docker": {
      "command": "/absolute/path/to/docker-mcp/bin/docker-mcp-server.js"
    }
  }
}

Claude Desktop でのテスト（ローカル開発）

ローカルで開発していて、Claude Desktop でテストする場合：

1. プロジェクトをビルドします。

npm run build

2. Claude Desktop の設定に追加します。
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "docker": {
      "command": "node",
      "args": ["/absolute/path/to/docker-mcp/dist/index.js"]
    }
  }
}

MCP Inspector でのテスト（CLI）

MCP Inspector または任意の MCP クライアントを使用して、サーバーをテストできます。

# Build first
npm run build

# The server communicates via stdio, so you can pipe commands to it
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。