Docker Hub MCPサーバーでClaudeにイメージを検索・選定させる

Docker Hub MCPサーバーで何ができるか

Docker Hub MCPサーバーは、Docker Hub APIをMCP経由でLLMに公開するサーバーです。イメージのタグ・説明・リポジトリの統計といった構造化データをClaudeに直接渡せます。「軽量なNode.jsイメージを探して」のような自然言語の依頼から、タグ名やリポジトリ名を覚えていなくても目的のイメージにたどり着けます。

リポジトリの作成やDockerfileの取得・設定といった書き込み操作も、PAT(パーソナルアクセストークン)を設定すれば自然言語の指示でこなせます。

Docker MCP Toolkitの一般的な接続手順を扱った記事とは違い、本記事はDocker Hub専用のMCPサーバーが提供する機能と、その認証まわりに絞って扱います。前提はDockerのインストールとNode.js 22以降(ローカルビルドする場合)です。書き込み操作をさせたい場合は、Docker Hubのパーソナルアクセストークンも要ります。

Dockerイメージ選びの難しさは、タグの命名規則やメンテナンス状況、公式イメージかどうかの判断材料がイメージごとにばらばらな点にあります。モデルの学習データだけで答えさせると、古い情報や存在しないタグ名が出ることがあります。Docker Hub MCPサーバーを通すと、Claudeは実際のDocker Hub APIからメタデータを取得して答えるため、この種の取り違えを避けやすくなります。

どちらの方法でつなぐか

Claude Codeからこのサーバーを使う経路は2つあり、Claude Codeの側に登録される名前と中身が違います。

Docker MCP Toolkit経由でセットアップする

Docker Desktopを使っている場合は、GUIだけで完結します。画面の名称はDocker Desktop 4.62以降のものです。

Claude Codeへの接続は、CLIからもできます。docker mcp client connectの対応クライアントにclaude-codeが含まれ、--profileでプロファイルを指定します。

docker mcp client connect claude-code --profile <id>

接続後にClaude Codeで見えるのは、docker-hubではなくゲートウェイ名のMCP_DOCKERです。Dockerの手順ページには、claude mcp listの出力例としてMCP_DOCKER: docker mcp gateway run - ✓ Connectedが載っています。このコマンドの前提となるclaude mcp addのスコープや認証の詳細は別記事にまとめています。

ローカルビルドしてClaude Codeに直接つなぐ

Docker Desktopを使わない場合や、stdioで直接つなぎたい場合はソースからビルドします。

git clone https://github.com/docker/hub-mcp.git
cd hub-mcp
npm install
npm run build

ビルドが終わったら、Claude Codeにclaude mcp addでstdioサーバーとして登録します。パブリックリポジトリの検索だけなら認証は不要です。

claude mcp add --transport stdio docker-hub \
  -- node /FULL/PATH/TO/hub-mcp/dist/index.js --transport=stdio

自分のリポジトリを検索・作成・更新する書き込み操作までさせたい場合は、Docker Hubのユーザー名とPATを渡します。ユーザー名は--username、PATは環境変数HUB_PAT_TOKENです。

claude mcp add --env HUB_PAT_TOKEN=your_pat_token --transport stdio docker-hub \
  -- node /FULL/PATH/TO/hub-mcp/dist/index.js \
     --transport=stdio --username=your_hub_username

PATを渡さない場合、このMCPサーバーはDocker Hub上の公開コンテンツしか扱えません。自分のnamespace配下のリポジトリ一覧取得やDockerfileの設定までさせたいときだけ、PATを設定します。

PATの保存先はスコープで変わる

PATを渡したclaude mcp addは、スコープによって保存先が変わります。Claude Code v2.1.287のclaude mcp add --helpは、既定のスコープを次のように示します。

-e, --env <env...>           Set environment variables (e.g. -e KEY=value)
-s, --scope <scope>          Configuration scope (local, user, or project)
                             (default: "local")
-t, --transport <transport>  Transport type (stdio, sse, http). Defaults to
                             stdio if not specified.

既定のlocalスコープはユーザーの~/.claude.jsonに保存され、バージョン管理には入りません。-s projectを付けると、プロジェクト直下の.mcp.jsonに書かれます。v2.1.287で、空の一時ディレクトリに上のコマンドへ-s projectと偽のPATを付けて実行すると、PATは平文のままenvに残りました。

{
  "mcpServers": {
    "docker-hub": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/FULL/PATH/TO/hub-mcp/dist/index.js",
        "--transport=stdio",
        "--username=your_hub_username"
      ],
      "env": {
        "HUB_PAT_TOKEN": "dummy_pat"
      }
    }
  }
}

.mcp.jsonはチームで共有する前提のファイルなので、そのままコミットするとPATも一緒に共有されます。チーム共有にしたい場合は、envの値を${HUB_PAT_TOKEN}のように環境変数の参照にしておく方法があります。.mcp.jsonはcommand・args・envなどで${VAR}の展開に対応しているため、PAT本体は各自のシェルの環境変数に置けます。

HTTPトランスポートを使うときのセキュリティ注意点

このサーバーはstdioに加えてHTTPトランスポートにも対応しています。既定の安全策を理解せずにネットワークへ公開すると、Docker Hubアカウントの操作権限ごと他人に渡すことになりかねません。

HTTPトランスポートでのツール呼び出しは、サーバー運用者のPAT(HUB_PAT_TOKEN)を使って実行されます。HTTPエンドポイントに到達できる人は誰でも、そのDocker Hubアカウントとしてリポジトリの作成・変更まで行えてしまいます。このため、公式リポジトリはHTTPトランスポートを既定で厳しく制限しています。

認証付きでHTTPトランスポートを起動するコマンドは次のとおりです。

MCP_AUTH_TOKEN=<a_long_random_secret> npm start -- --transport=http

コンテナ内からHTTPトランスポートを公開したい場合は、--host=0.0.0.0でバインド先を広げます。あわせて、--allowed-hostsと--allowed-originsでアクセス元を絞ります。

MCP_AUTH_TOKEN=<a_long_random_secret> npm start -- \
  --transport=http --host=0.0.0.0 \
  --allowed-hosts=my-host.internal --allowed-origins=https://my-app.example.com

--allow-unauthenticatedは認証を完全に無効化し、そのポートに到達できる誰にでもPATを渡すのと同じ状態にします。信頼できる隔離されたネットワーク以外では使わないでください。Claude Codeからの利用に限るなら、外部公開が要らないstdioトランスポートの方が、この種のリスクをそもそも持ち込みません。

自然言語でできる操作の例

セットアップが済めば、コマンドやタグ名を正確に覚えていなくても目的のイメージにたどり着けます。

• 「公式のnginxイメージを検索して」: 検索結果をsearchツールで取得
• 「フットプリントの小さいNode.jsイメージを探して」: サイズや用途で絞り込んだ検索
• 「自分のnamespaceで直近60日プッシュされていないリポジトリを教えて」: リポジトリ一覧とタグ情報を突き合わせた棚卸し
• 「my-web-appリポジトリにv1.2.0というタグが存在するか確認して」: タグの存在チェック

Dockerのドキュメントに載っている依頼文の例は、docker ai "..."のようにDockerのAIアシスタント(Ask Gordon)向けの書き方です。Claude Codeではdocker aiを付けず、同じ文面をそのままプロンプトに書きます。上の例は、それらを日本語にしたものです。DockerのドキュメントにあるイメージのPull・Pushの例(docker ai "Pull the latest postgres image")は、このMCPサーバーにはPull・Pushのツールがないため、サーバー経由では実行できません。

これらは、search・list-repositories-by-namespace・list-repository-tags・check-repository-tagといった個別ツールの組み合わせで実現されます。ツール名を覚える必要はなく、自然な依頼文のままClaudeが適切なツールを選びます。

「フットプリントの小さいイメージを探して」「本番運用に向いたデータベースイメージを探して」のような依頼は、単純なタグ検索では拾いにくい要求です。サーバーがイメージのメタデータ(説明文・カテゴリ・アーキテクチャ対応状況など)を構造化データとして渡すため、曖昧な条件からの絞り込みが自然文のまま成立します。Ubuntuのバージョン選びのように、複数の候補を比較して選ばせる依頼にも向いています。

対応ツールの範囲

Docker Hub MCPサーバーのツールは、大きく6つの系統に分かれます。

docker-hardened-imagesツールが返すDocker Hardened Imagesは、CVEの少ない最小構成イメージを提供する別製品で、Dockerのドキュメントにはアクセスにサブスクリプションが必要と注記されています。

ツール名がページによって違う

ツールの一覧は、Dockerドキュメントの表とGitHubのREADMEで内容が食い違います。Dockerドキュメントの表は14個で、名前はハイフン区切りです(list-repositories-by-namespaceなど)。READMEは11個で、名前はアンダースコア区切りです(list_repositories_by_namespaceなど)。

READMEの一覧には、check-repository-tagsと、Dockerfileの2つのツールがありません。手元のサーバーで使えるツールを確かめたいときは、Claude Codeに「このサーバーのツールを一覧にして」と頼む方法があります。

よくあるつまずき

• ローカルビルドしたのにサーバーが起動しない: npm run buildを実行し忘れているとdist/index.jsが存在せずエラーになります。クローン直後は必ずビルドしてからclaude mcp addします
• 書き込み系のツールが動かない: PATを設定していないと、このサーバーは公開コンテンツの検索にしか使えません。リポジトリ作成や更新をさせたい場合はHUB_PAT_TOKENを必ず設定します
• HTTPトランスポートを使ったら起動しなかった: --transport=httpは認証設定が無いと既定で起動を拒否します。エラーメッセージの指示どおりMCP_AUTH_TOKENを設定するか、必要な場合のみ--allow-unauthenticatedを使います(推奨はしません)
• nvmでNode.jsを管理している: commandにnodeとだけ書くと想定と違うバージョンが呼ばれることがあります。which nodeで確かめたフルパスをcommandに指定すると安定します
• VS Codeなど他クライアントの設定をそのまま流用したい: Dockerのドキュメントの設定例は、Claude Desktop向けとVS Code向けでユーザー名の渡し方が違います。前者は--username引数、後者はHUB_USERNAME環境変数です。READMEは--usernameで書かれているので、本記事のclaude mcp addの例もそれに合わせています。VS Code向けのJSONはmcpServersブロックで書かれており、claude mcp addの引数に読み替える必要があります

まとめ

Docker Desktopを既に使っているならToolkit経由でMCP_DOCKERとして、使っていないならローカルビルドのdocker-hubとして、どちらでもClaude Codeから呼び出せます。検索だけなら認証は不要です。

PATを渡すときは、-s projectで.mcp.jsonに平文のまま残さないこと、HTTPトランスポートで認証を外さないことが、Docker Hubアカウントを守る分かれ目になります。