Docker MCP Server

🚀 Docker MCPサーバー

AIアシスタントやアプリケーションにDockerコンテナ実行機能を提供するModel Context Protocol (MCP)サーバーです。このサーバーにより、コンテナ化された環境内でコマンドやファイル操作を分離して実行できます。

🚀 クイックスタート

オプション1: npxで実行（推奨）

# npxで直接実行（インストール不要）
npx docker-mcp-server

# カスタムコンテナ名で実行
npx docker-mcp-server --container-name my-container

# ヘルプと利用可能なオプションを表示
npx docker-mcp-server --help

前提条件: Dockerがインストールされ、実行中であり、コンテナが利用可能である必要があります。

オプション2: グローバルにインストール

# グローバルにインストール
npm install -g docker-mcp-server

# どこからでも実行
docker-mcp-server --container-name my-container

オプション3: 開発環境のセットアップ

1. クローンとセットアップ

git clone <your-repository-url>
cd docker-mcp
npm install

2. 環境の起動

# Docker環境をリセットして起動
./reset-docker.sh

このスクリプトは以下のことを行います:

• 既存のコンテナを停止する
• /tmpディレクトリをクリーンアップする
• コンテナをバックグラウンドで起動する
• インタラクティブシェルに入る

3. MCPサーバーのビルドと実行

# TypeScriptをビルド
npm run build

# MCPサーバーを起動（デフォルトのコンテナ名: mcp-container）
npm start

# カスタムコンテナ名で起動
npm start -- --container-name my-custom-container

# または、ビルドと起動を1つのコマンドで実行
npm run dev

# カスタムコンテナでビルドと起動
npm run dev -- --container-name my-custom-container

✨ 主な機能

• 安全なコマンド実行: 分離されたDockerコンテナ内でシェルコマンドを実行する
• ファイル操作: コンテナ内のファイルを読み取り、書き込み、編集、検索する
• プロセス管理: 一意のIDで長時間実行されるプロセスを追跡する
• インタラクティブ入力: 実行中のプロセスに入力を送信する
• スマートタイムアウト: 出力のアクティビティに基づくインテリジェントなプロセスタイムアウト処理

🏗️ アーキテクチャ

このMCPサーバーは、MCPクライアント（Claude Codeなど）とDockerコンテナ環境の間の橋渡しとして機能します:

MCP Client (Claude Code) ↔ MCP Server ↔ Docker Container (Debian + Node.js)
                                              ↓
                                        Host ./tmp directory

コアコンポーネント

• MCPサーバー (src/index.ts) - @modelcontextprotocol/sdkを使用するTypeScriptサーバー
• Dockerコンテナ - Node.jsと開発ツールを備えたDebianベースのコンテナ
• ファイルマウント - 永続化のためにホストの./tmpディレクトリがコンテナの/appにマウントされる
• プロセス追跡 - 一意のIDとモニタリングによるバックグラウンドプロセス管理

📋 前提条件

• Dockerがインストールされ、実行中であること
• コンテナの簡単な管理のためのDocker Compose
• MCPサーバーのためのNode.js（v18以上）
• 依存関係管理のためのnpm

🔧 CLIの使い方

MCPサーバーは以下のコマンドラインオプションをサポートしています:

# ヘルプと利用可能なオプションを表示
node dist/index.js --help

# デフォルトのコンテナ名（mcp-container）で起動
node dist/index.js

# カスタムコンテナ名で起動
node dist/index.js --container-name my-dev-container
node dist/index.js -c my-dev-container

# バージョンを表示
node dist/index.js --version

コンテナ名の設定

Dockerコンテナ名はいくつかの方法で設定できます:

1. デフォルト: オプションが指定されない場合はmcp-containerを使用する
2. CLI引数: --container-nameまたは-cフラグ
3. 複数インスタンス: 異なるコンテナで複数のMCPサーバーを実行する

# ターミナル1: 開発用コンテナ
npm run dev -- --container-name dev-container

# ターミナル2: テスト用コンテナ  
npm run dev -- --container-name test-container

# ターミナル3: 本番用コンテナ
npm run dev -- --container-name prod-container

⚙️ MCPクライアントの設定

Claude DesktopなどのMCPクライアントでこのサーバーを使用するには、以下の設定を追加します:

Claude Desktopの設定

Claude Desktopの設定ファイルに追加します:

場所:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

設定:

{
  "mcpServers": {
    "docker-mcp": {
      "command": "npx",
      "args": [
        "-y", "docker-mcp-server@latest"
      ]
    }
  }
}

カスタムコンテナを使用する場合:

{
  "mcpServers": {
    "docker-mcp": {
      "command": "npx",
      "args": [
        "-y", "docker-mcp-server@latest",
        "--container-name", "my-dev-container"
      ]
    }
  }
}

その他のMCPクライアント

その他のMCPクライアントでは、以下のコマンドを使用します:

npx -y docker-mcp-server@latest

MCP使用の前提条件

1. Dockerコンテナが実行中であること:

   docker run -d --name mcp-container -v ./workspace:/app node:current-bookworm sleep infinity
   

2. コンテナにプロジェクトファイルがあること:

   • ワークスペースディレクトリをコンテナの/appにマウントする
   • コンテナに必要な開発ツールがインストールされていることを確認する

3. 設定を追加した後にClaude Desktopを再起動する

検証

設定後、Claude DesktopはDocker MCPサーバーが接続され、コンテナベースの開発に必要なすべてのツールにアクセスできることを表示するはずです。

🛠️ 開発コマンド

コンテナ管理

# Docker環境をリセット（コンテナを停止、/tmpをクリーンアップ、再起動）
./reset-docker.sh

# コンテナをバックグラウンドで起動
docker-compose up -d

# コンテナを停止して削除
docker-compose down

# コンテナにインタラクティブシェルで入る
docker exec -it mcp-container bash

ビルドと実行

# TypeScriptをJavaScriptにコンパイルして/distに出力
npm run build

# コンパイルされたMCPサーバーを実行
npm start

# ビルドと起動を1つのコマンドで実行
npm run dev

🔧 利用可能なMCPツール

サーバーはMCPクライアントに以下のツールを提供します:

🚀 コマンド実行

execute_command

Dockerコンテナ内でシェルコマンドを実行する

コンテナ環境内で任意のシェルコマンドを実行し、インテリジェントなプロセス追跡とタイムアウト処理を行います。

パラメータ:

• command (文字列) - コンテナ内で実行するシェルコマンド
• rationale (文字列) - このコマンドを実行する理由の説明
• maxWaitTime (数値、オプション) - エージェントに戻る前に待つ最大秒数（デフォルト: 20）

機能:

• 長時間実行されるプロセスの自動バックグラウンド化
• 出力のアクティビティに基づくスマートタイムアウト
• モニタリング用のプロセスIDの返却
• リアルタイムの出力キャプチャ

check_process

IDでバックグラウンドプロセスをモニタリングする

execute_commandで開始されたバックグラウンドプロセスのステータスと出力を確認します。

パラメータ:

• processId (文字列) - 長時間実行されるコマンドから返されたプロセスID
• rationale (文字列) - このプロセスを確認する理由の説明

返り値:

• プロセスのステータス（実行中/完了）
• 現在の出力（stdout/stderr）
• 終了コード（完了した場合）
• 実行時間

send_input

実行中のバックグラウンドプロセスに入力を送信する

ユーザー入力を待っているインタラクティブなプロセスに入力データを送信します。

パラメータ:

• processId (文字列) - 実行中のプロセスのプロセスID
• input (文字列) - プロセスに送信する入力
• rationale (文字列) - このプロセスに入力を送信する理由の説明
• autoNewline (ブール値、オプション) - 自動的に改行を追加するかどうか（デフォルト: true）

📁 ファイル操作

file_read

コンテナのファイルシステムからファイルを読み取る

オフセットと制限パラメータを使用して大きなファイルをサポートしながら、ファイルの内容を読み取ります。

パラメータ:

• filePath (文字列) - 読み取るファイルのパス（コンテナ内の/appに対する相対パス）
• rationale (文字列) - このファイルを読み取る理由の説明
• offset (数値、オプション) - 開始行番号（0から始まる、デフォルト: 0）
• limit (数値、オプション) - 読み取る最大行数（デフォルト: 2000）

機能:

• 行番号付きの出力（cat -n形式）
• ページングによる大きなファイルのサポート
• バイナリファイルの検出と拒否
• 制限付きのコンテキストセーフな読み取り

file_write

コンテナ内のファイルを作成または上書きする

安全チェックとディレクトリ作成を行いながら、ファイルに内容を書き込みます。

パラメータ:

• filePath (文字列) - 書き込むファイルのパス（コンテナ内の/appに対する相対パス）
• content (文字列) - ファイルに書き込む内容
• rationale (文字列) - このファイルを書き込む理由の説明

安全機能:

• 自動ディレクトリ作成
• 内容の長さ報告
• ファイルの存在確認
• 安全な内容の送信

重要: ファイルを書き込む前に、file_readを使用してファイルの現在の状態とコンテキストを理解する必要があります。

file_edit

ファイル内で正確な文字列置換を行う

バックアップ保護付きで、正確な文字列の一致と置換を使用してファイルを編集します。

パラメータ:

• filePath (文字列) - 編集するファイルのパス（コンテナ内の/appに対する相対パス）
• oldString (文字列) - 置換する正確なテキスト
• newString (文字列) - 置換するテキスト
• rationale (文字列) - このファイルを編集する理由の説明
• replaceAll (ブール値、オプション) - すべての出現箇所を置換するかどうか（デフォルト: false）

安全機能:

• 編集前の自動バックアップ作成
• 正確な文字列一致の要件
• 安全なテキスト送信のためのBase64エンコーディング
• 失敗時のバックアップ復元

重要: 正確なテキストを一致させ、ファイルの現在の状態を理解するために、最初にfile_readを使用する必要があります。

file_ls

フィルタリング付きでディレクトリの内容をリストする

インテリジェントなフィルタリングと出力制限で、ファイルとディレクトリをリストします。

パラメータ:

• path (文字列、オプション) - リストするディレクトリのパス（デフォルト: カレントディレクトリ）
• rationale (文字列) - このディレクトリをリストする理由の説明
• ignore (文字列の配列、オプション) - 無視するグロブパターンのリスト

機能:

• 組み込みの無視パターン（node_modules、.git、distなど）
• 詳細なファイル情報（パーミッション、サイズ、タイムスタンプ）
• 出力制限（100エントリ）とオーバーフロー通知
• スマートパターンフィルタリング

file_grep

正規表現をサポートしたファイル内容の検索

強力なgrep機能を使用して、ファイル内のパターンを検索し、結果を制限します。

パラメータ:

• pattern (文字列) - 検索パターン（正規表現をサポート）
• rationale (文字列) - このパターンを検索する理由の説明
• path (文字列、オプション) - 検索するディレクトリ（デフォルト: カレントディレクトリ）
• include (文字列、オプション) - 含めるファイルパターン（例: '.js', '.{ts,tsx}'）
• caseInsensitive (ブール値、オプション) - 大文字小文字を区別しない検索（デフォルト: false）
• maxResults (数値、オプション) - 返す最大結果数（デフォルト: 100）

機能:

• 再帰的なディレクトリ検索
• ファイルタイプフィルタリング
• 行番号表示
• オーバーフロー報告付きの結果数制限
• 正規表現パターンサポート

📊 プロセス管理

コマンドはインテリジェントなタイムアウト処理で実行されます:

• デフォルトタイムアウト: バックグラウンド化する前に20秒の非アクティビティ
• 最大タイムアウト: 絶対的な制限として10分
• プロセス追跡: バックグラウンドプロセスにはモニタリング用の一意のIDが付与される
• スマートウェイト: 固定間隔ではなく、出力のアクティビティに基づく

プロセスフローの例

# 長時間実行されるコマンドは自動的にバックグラウンド化される
process_id = execute_command("npm install", "Installing dependencies")

# 後でステータスを確認
check_process(process_id, "Checking installation progress")

# インタラクティブなプロセスに入力を送信
send_input(process_id, "y\n", "Confirming prompt")

🔒 セキュリティに関する考慮事項

⚠️ 重要なセキュリティ注意事項

• このサーバーはMCPクライアントに直接Dockerコンテナへのアクセスを提供します。
• コンテナはホストの./tmpディレクトリにアクセスできます。
• コマンドはコンテナレベルの権限で実行されます。
• ネットワークアクセスはホストネットワーキングモードで有効になっています。

推奨されるセキュリティ対策

1. コンテナアクセスを制限する: MCPサーバーにアクセスできるユーザーを制限する
2. ファイル操作を監視する: ./tmpディレクトリの内容を定期的に監査する
3. ネットワーク分離を行う: ホストモードの代わりにカスタムネットワークを使用することを検討する
4. リソース制限を追加する: コンテナにCPUとメモリの制約を追加する
5. 監査ログを監視する: コンテナのコマンド実行とファイルアクセスを監視する

🚨 トラブルシューティング

一般的な問題

コンテナが起動しない場合:

# Dockerが実行中であることを確認
docker info

# 環境をリセット
./reset-docker.sh

パーミッションエラーが発生する場合:

# tmpディレクトリが書き込み可能であることを確認
chmod 755 ./tmp

MCPサーバーの接続に問題がある場合:

# サーバーが実行中であることを確認
npm run build && npm start

# コンテナにアクセスできることを確認
docker exec -it mcp-container echo "Hello"

コンテナ名エラーが発生する場合:

# コンテナが存在するかどうかを確認
docker ps -a

# 正しい名前を見つけるためにすべてのコンテナをリストする
docker ps --format "table {{.Names}}\t{{.Status}}"

# 正しいコンテナ名で起動
npm start -- --container-name your-actual-container-name

# サーバーは起動時にコンテナが存在することを検証します

複数のコンテナをセットアップする場合:

# 異なる名前で追加のコンテナを起動
docker run -d --name dev-container -v ./tmp:/app node:current-bookworm sleep infinity
docker run -d --name test-container -v ./tmp:/app node:current-bookworm sleep infinity

# 各コンテナに対してMCPサーバーを実行
npm run dev -- --container-name dev-container    # ターミナル1
npm run dev -- --container-name test-container   # ターミナル2

プロセスタイムアウトが発生する場合:

• execute_commandのmaxWaitTimeパラメータを調整する
• check_processを使用して長時間実行される操作を監視する
• 複雑な操作を小さなステップに分割することを検討する

🤝 コントリビューション

1. リポジトリをフォークする
2. 機能ブランチを作成する (git checkout -b feature/amazing-feature)
3. 変更を加える
4. コンテナ環境で十分にテストする
5. 変更をコミットする (git commit -m 'Add amazing feature')
6. ブランチにプッシュする (git push origin feature/amazing-feature)
7. プルリクエストを作成する

開発ガイドライン

• TypeScriptのベストプラクティスに従う
• 包括的なエラーハンドリングを追加する
• すべてのツール操作に理由パラメータを含める
• 高速実行と長時間実行の両方のコマンドでテストする
• 新しいMCPツールや機能をドキュメント化する

📦 npmへの公開

このパッケージをグローバルに使用するためにnpmに公開するには:

前提条件

1. npmjs.comでnpmアカウントを作成する
2. npmにログインする: npm login
3. package.jsonを自分の詳細で更新する:
   • author: あなたの名前とメールアドレス
   • repository: あなたのGitHubリポジトリのURL
   • homepage: あなたのプロジェクトのホームページ
   • bugs: あなたの問題追跡URL

公開手順

# 1. バージョンを更新（パッチ/マイナー/メジャー）
npm version patch

# 2. プロジェクトをビルド
npm run build

# 3. パッケージをローカルでテスト
npm pack
npm install -g ./docker-mcp-server-1.0.1.tgz

# 4. npx機能をテスト
npx docker-mcp-server --help

# 5. npmに公開
npm publish

# 6. インストールが正常に動作することを確認
npx docker-mcp-server@latest --help

公開後

• あなたのパッケージはhttps://www.npmjs.com/package/docker-mcp-serverで利用可能になります。
• ユーザーはnpx docker-mcp-serverで実行できます。
• グローバルインストール: npm install -g docker-mcp-server

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細についてはLICENSEファイルを参照してください。

🙋‍♂️ サポート

• 🐛 バグ報告: 詳細な再現手順を添，イシューを作成してください
• 💡 機能リクエスト: ユースケースと提案された解決策を添えてイシューを作成してください
• 📖 ドキュメント: AIアシスタント固有のガイダンスについてはCLAUDE.mdファイルを確認してください
• 💬 質問: 一般的な質問やヘルプについてはディスカッションを作成してください

---

Built for the Model Context Protocol ecosystem 🤖