Docker MCP ToolkitでClaude Codeからコンテナを操作する設定

Docker MCP ToolkitでClaude Codeから何ができるようになるか

Docker MCP Toolkitは、Docker Desktopに統合されたMCPサーバーの管理機能です。MCPサーバーをコンテナとして分離実行し、プロファイル単位でまとめて管理できます。Claude Codeをクライアントとして接続すると、GitHubやPlaywrightのようなMCPサーバーをnpxやuvxで個別にインストールせず、Dockerコンテナ経由でClaude Codeのセッションから呼び出せるようになります。依存関係の管理やランタイムの用意が不要になる点が、素のstdioサーバーを個別追加する方式との主な違いです。

前提はClaude Codeのインストール済み環境と、docker mcpコマンドが使えるDocker Desktopです。バージョンはDocker Docsの手順ページが4.62以降、GitHubのREADMEが4.59以上と書いており、ページによって数字が違います。4.62以降なら両方を満たします。docker mcpはDocker Desktopに同梱されているため、追加インストールは要りません。

プロファイルとゲートウェイの役割(profile / gateway)

Docker MCP Toolkitは3つの要素で構成されます。クライアントを接続するときに指定するのは、このうちプロファイルです。

セキュリティ面では、ビルド時の対策(カタログのmcp/配下のイメージはDockerがビルドして署名し、SBOMを添付)とランタイムの対策(サーバーごとにCPU1コア・メモリ2GBの制限、ファイルシステムへの既定アクセスなし、シークレットを含むリクエストの遮断)の両方が組み込まれています。個別にMCPサーバーをローカルへインストールするより、隔離の粒度が細かい構成です。

ステップ1: プロファイルを作りサーバーを追加する

まずプロファイルを作成し、使うMCPサーバーを追加します。

# プロファイルを作成
docker mcp profile create --name web-dev
 
# カタログのサーバー一覧を確認(サーバーIDを控える)
docker mcp catalog server ls mcp/docker-mcp-catalog
 
# プロファイルにサーバーを追加(複数指定可)
docker mcp profile server add web-dev \
  --server catalog://mcp/docker-mcp-catalog/github-official \
  --server catalog://mcp/docker-mcp-catalog/playwright

サーバーはURI形式で指定します。カタログ由来ならcatalog://<catalog-ref>/<server-id>、自前のDockerイメージならdocker://<image>:<tag>、MCPコミュニティレジストリならhttps://<url>/v0/servers/<uuid>、ローカルのYAML/JSON定義ならfile://<path>です。サーバーIDはDocker Desktopの「MCP Toolkit」→「Catalog」の該当サーバー詳細か、catalog server lsの出力名で確認できます。GitHubやPlaywrightのような汎用ツールのほかに、Docker Hub自体をLLMから検索・操作できるMCPサーバーもあります。

ステップ2: Claude Codeをクライアントとして接続する

プロファイルができたら、Claude Codeをクライアントとして接続します。Docker公式のCLIプラグインリポジトリ(docker/mcp-gateway)のREADMEにあるclient connectの書式は、docker mcp client connect <client-name> --profile <profile-id>です。claude-codeを当てはめると、次のコマンドになります。

docker mcp client connect claude-code --profile web-dev

接続先のクライアント名はdocker mcp client lsで一覧できます。同じREADMEには、CLAUDE_CONFIG_DIRを設定していると設定の書き込み先が$CLAUDE_CONFIG_DIR/.claude.jsonに変わるという説明があります。作業用と私用でClaude Codeの設定ディレクトリを分けている場合は、書き込み先がどちらになるかを先に決めてから実行します。

Docker Docsの確認例では、Docker Desktopから接続したClaude Codeのサーバー名はMCP_DOCKERで、claude mcp listの出力はMCP_DOCKER: docker mcp gateway run - ✓ Connectedの形です。

コマンドが使えない場合や、登録内容を手元で見ながら進めたい場合は、claude mcp addでゲートウェイをstdioサーバーとして直接登録する方法があります。Claude Code公式ドキュメントが示す、stdioサーバーを追加する標準の書き方です。

claude mcp add --transport stdio docker-toolkit \
  -- docker mcp gateway run --profile web-dev

--より前がClaude Code自身のオプション、より後がゲートウェイに渡すコマンドという区切りです。claude mcp add構文の詳細(スコープの使い分けや環境変数展開など)はClaude Code MCP設定ガイドにまとめています。Docker公式ドキュメントが示す手動接続例は、serversキーを使う汎用のJSON形式と、Claude Desktop向けのmcpServers形式です。Claude Codeのclaude mcp add構文とは書き方が異なります。

チームで同じ接続を共有する(--scope project)

--scope projectを付けると、登録内容がプロジェクトルートの.mcp.jsonに書かれ、リポジトリに入れて共有できます。v2.1.287で上のコマンドに--scope projectを足して実行したところ、次のファイルができました。

{
  "mcpServers": {
    "docker-toolkit": {
      "type": "stdio",
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "web-dev"],
      "env": {}
    }
  }
}

.mcp.jsonのサーバーは、各メンバーがclaudeを対話で起動して承認するまでPending approvalのままです。承認前は接続もヘルスチェックも行われません。

OAuth認証が必要なサーバーを追加する

GitHubやNotionのように外部サービスと連携するMCPサーバーは、OAuth認証を求めることがあります。Docker MCP ToolkitはこのOAuthフローも管理下に置きます。Docker Desktopの「MCP Toolkit」→「Catalog」から該当サーバーを追加し、サーバーの「Configuration」タブでOAuth認証方式を選ぶと、ブラウザで認可ページが開きます。認可が終わったら「OAuth」タブで連携済みのサービス一覧を確認でき、不要になった連携は「Revoke」で個別に取り消せます。Claude Code自身がOAuthのやり取りを仲介する必要はなく、認証はプロファイルに紐づいたサーバー単位で完結します。

認証情報の後始末には注意点があります。Docker Docsには、Docker Desktop 4.43.0以降は認証情報がDocker Desktop VM内に保存されると書かれています。保存された認証情報はdocker mcp secret lsで一覧し、docker mcp secret rmで削除し、OAuthはdocker mcp oauth revokeで取り消します。サーバーを外してもイメージが残るのと同じく、認証情報も自動では消えません。サーバーを使い終えたら、認証情報も別に消します。

ステップ3: 接続を確認する

接続後はclaude mcp listまたはclaude mcp get docker-toolkitで状態を確認します。Claude Codeのセッション内では/mcpパネルからも同じ情報が見られます。✔ Connectedが表示されれば、プロファイル内のサーバーがコンテナ経由で呼び出せる状態です。

Failed to connectになったときの切り分け

接続に失敗すると、claude mcp getは次のように表示します。これはv2.1.287で、docker mcpプラグインが入っていないDocker 20.10の環境に、上のclaude mcp addで登録して実行した出力です。

docker-toolkit:
  Scope: Local config (private to you in this project)
  Status: ✘ Failed to connect
  Issue: CONNECTION_CLOSED: Connection closed
  Type: stdio
  Command: docker
  Args: mcp gateway run --profile web-dev

CONNECTION_CLOSEDは、ゲートウェイのプロセスがすぐ終了したことを示します。この環境で同じコマンドを直接実行するとunknown flag: --profileと出て終了しました。プラグインが無いとdocker本体が--profileを解釈できず、この表示になります。原因がClaude Code側かDocker側かは、次の順で切り分けられます。

「MCP Gateway」という名前が指す2つの機能

Docker公式ドキュメントを読むときに紛らわしいのが、「MCP Gateway」という名前が2つの異なる機能を指すことです。

docker mcp gateway runやclaude mcp addを手動で書くのは、挙動を細かく制御したい場合や、Docker Desktopなしで使う場合です。Docker Engineのみの環境では、GitHubリリースページからバイナリを取得し、~/.docker/cli-plugins/docker-mcpに配置してからchmod +xで実行権限を与えます。

プロファイルを共有し、見えるツールを絞る

プロジェクトごとにプロファイルを分けておけば、--profileの値を変えるだけで、Claude Codeから見えるサーバーの範囲も切り替わります。同じプロファイルをチームで使う方法は、Docker Docsに2つ載っています。

# バージョン管理で共有: ファイルに書き出して、メンバーが取り込む
mkdir -p .docker
docker mcp profile export web-dev .docker/mcp-profile.json
docker mcp profile import .docker/mcp-profile.json
 
# OCIレジストリで共有: push / pull
docker mcp profile push web-dev registry.example.com/profiles/web-dev:v1
docker mcp profile pull registry.example.com/profiles/web-dev:v1

どちらの方法でも、認証情報は共有されません。メンバーはOAuthやシークレットを自分で設定し直します。

サーバー単位だけでなく、ツール単位でも絞れます。GitHubのREADMEには、docker mcp tools lsでツールを一覧し、docker mcp profile tools web-dev --disable <サーバー>.<ツール>で個別に無効化する例があります。コンテナではなくデスクトップアプリケーション自体をMCP経由で操作する例は、Unreal Engine 5.8のMCP設定ガイドにあります。

よくあるつまずき

• 「Docker Desktop is not running」エラーが出る: Dockerデーモン自体は動いているのに出る場合、WSL2やDocker CEなどDocker Desktop本体を使わない環境で起きやすい症状です。DOCKER_MCP_IN_CONTAINER=1を環境変数に設定すると、Desktop本体の機能チェックを回避できます
• プロファイル機能が動かない: Docker Desktop以外の環境(Docker CE・WSL2・コンテナ内)では、プロファイル機能が既定で無効です。docker mcp feature enable profilesを先に実行します
• --profileを省略したらサーバーが1つも呼び出せない: docker mcp gateway runは--profileを省略するとdefaultプロファイルを使いますが、何も追加していなければ空です。空のプロファイルへ接続してもツールは1つも見えません
• VS Codeでも同時に使いたい: docker mcp client connect vscode --profile web-devで別クライアントとして同じプロファイルに接続できます。生成される.vscode/mcp.jsonはユーザー固有のファイルなので.gitignoreに追加します
• GitHubやNotionなどリモートのサーバーがカタログに出ない: ローカルのカタログが古い可能性があります。docker mcp catalog updateを実行してから、Catalogタブを開き直します
• Claude Code自体をDockerコンテナで動かしている: 本記事はClaude Codeから外部のDockerコンテナを操作する手順で、Claude Code自体をコンテナ内で実行する構成とは逆方向です。両方を同時に組む場合は、コンテナ内のClaude Codeからホスト側のDockerデーモンにアクセスできるかを別途確かめます

まとめ

チームで使うなら、.mcp.jsonの--scope projectとプロファイルのexportを組み合わせ、認証情報だけは各自で入れる前提にします。