Podman MCPサーバーの使い方 — Dockerとの違いとrootless接続

Podman MCPサーバーは、PodmanまたはDockerのコンテナ操作をClaude Codeから自然文で実行できるようにするMCPサーバーです。コンテナの一覧・起動・停止、イメージのビルドとプッシュ、ネットワークやボリュームの一覧までを13個のツールとして提供します。最新版はv0.0.15(2026年2月27日リリース)で、バージョンは0.0系です。

名前は「Podman」ですが、Dockerだけが入っている環境でも動きます。裏側にはPodman REST APIを直接呼ぶ実装とCLIラッパーの2系統があり、どちらを使うかはソケットの有無で決まります。接続まわりで迷う点はこの切り替えとソケットの探索順に集まります。

Podman MCPサーバーとは

Podman MCPサーバーはGoで書かれた、コンテナランタイム向けのMCPサーバーです。配布形態は3つあります。

• npm(npxで起動)
• PyPI(uvxで起動)
• GitHub Releasesのスタンドアロンバイナリ(v0.0.15ではdarwin・linux・windowsのamd64とarm64)

公式のMCP Registryに登録されているのは、このうちnpmとPyPIの2つです。v0.0.15のバイナリが必要な場合は、GitHub Releasesのページから取得します。

リポジトリはPodman本体のcontainers組織ではなく、個人のアカウント配下にあります。MCP Registryで「podman」と検索すると、PyPIパッケージmcp-podman-crunchtoolsという別のサーバーも見つかります。同じくPodman REST APIを使いますが、開発元もリポジトリも別なので、claude mcp addに書くパッケージ名は取り違えないようにします。この記事が扱うのはpodman-mcp-serverのほうです。

Claude CodeにPodman MCPを追加する

前提は、PodmanかDockerのどちらかが入っていて起動できることです。podman infoまたはdocker infoが正常終了すれば準備は完了です。

npmが入っている環境なら、claude mcp addの1行で追加できます。

claude mcp add podman -- npx -y podman-mcp-server@latest

Pythonの環境ならuvxでも同じことができます。

claude mcp add podman -- uvx podman-mcp-server@latest

--は、Claude Code自身のオプションと、サーバーを起動するコマンドを区切る記号です。--より後ろはそのままサーバー側に渡されます。

追加した範囲はどこまで効くか

プロジェクト側の手順書には「すべてのClaude Codeセッションで使えるようになる」と書かれています。一方、Claude Code v2.1.287のclaude mcp add --helpでは、--scopeの既定はlocalと表示されます。

-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.

Claude Code公式のMCPページでは、localは現在のプロジェクトだけで読み込まれ、チームには共有されません。設定は~/.claude.jsonに保存されます。userは自分のすべてのプロジェクトで読み込まれます。つまり、上の1行を実行したディレクトリ以外のプロジェクトでもコンテナを操作したいなら、--scope userを付けて追加します。チームで共有する場合は--scope projectで、設定は.mcp.jsonに書かれます。

claude mcp add --scope user podman -- npx -y podman-mcp-server@latest

追加後はclaude mcp listでpodmanが接続済みと表示されるかを確認します。表示されないときは、npxまたはuvxがPATH上にあるか、PodmanかDockerが起動しているかを先に確認します。ターミナルでnpx -y podman-mcp-server@latestを直接実行してサーバーが起動するかを試す方法も、プロジェクト側の手順書に載っています。

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

接続できていれば、こうした自然文の指示でコンテナ一覧の取得やイメージのビルド、ログの確認まで進みます。

apiとcli、2つの実装は何が違うか

バックエンドの実装は2種類あり、サーバーが起動時に自動で選びます。

--podman-implを付けると、実装を自動検出に任せず固定できます。

# CLIラッパーの実装を強制する
podman-mcp-server --podman-impl=cli
 
# REST API実装を強制する(Podmanソケットが必須)
podman-mcp-server --podman-impl=api

挙動の違いは3つの場面で出ます。

• 自動検出でapiが選ばれなかったときは、黙ってcliに切り替わります。ソケットが無効なだけでも動き続けるため、「Podmanのつもりが実はDocker CLI経由だった」という状態が起こりえます。
• --podman-impl=apiを明示してソケットにつながらないと、エラーになります。仕様書では、ソケットのパスと理由を返すと書かれています。
• apiで接続できたあとにAPI呼び出しが失敗しても、cliには切り替わりません。同じ操作を別の経路でやり直すと状態が食い違うおそれがあるため、エラーをそのまま返す設計です。

どちらの実装で動いているか迷ったときは、--podman-implで固定して挙動が変わるかを見ます。

rootlessでつながらないときはソケットの探索順を見る

api実装は、次の順にソケットを探します。

ここで目を引くのは、rootfulの既定パスがrootlessより先に見られる点です。rootfulとrootlessの両方のPodmanが同じマシンで動いていると、何も指定しない限りrootful側のソケットが先に候補になります。rootlessで起動したコンテナだけを見たいときは、CONTAINER_HOSTにrootless側のパスを指定します。

claude mcp add --scope user podman \
  -e CONTAINER_HOST=unix:///run/user/1000/podman/podman.sock \
  -- npx -y podman-mcp-server@latest

1000は自分のUIDに置き換えます。-eはMCPサーバーの環境変数として渡されます。-eの直後にサーバー名を置くと、名前が環境変数の組として読まれて追加に失敗するため、サーバー名を先に書きます。

ソケットがそもそも存在しない場合は、Podman側の設定が必要です。Podmanのドキュメントによると、rootless用のソケットはsystemdのユーザーユニットpodman.socketが$XDG_RUNTIME_DIR/podman/podman.sockで待ち受けます。ソケットアクティベーションなので、クライアントが接続した時点でpodman.serviceが起動し、一定時間使われないと止まります。

systemctl --user enable --now podman.socket

podman system serviceコマンドは、WindowsやmacOSのホストでPodmanを直接実行する場合には使えません。探索先の4つはLinuxのsystemd配下の既定パスなので、それ以外の環境でソケットの場所が違うときは、CONTAINER_HOSTで指定します。

apiで動かすときの権限の重さ

Podmanのドキュメントは、REST APIについて「Podmanのすべての機能へのフルアクセスを与え、APIを実行しているユーザーとして任意のコード実行を許す」と書いています。アクセスの制限と監査はできません。守りはUnixソケットのファイル権限だけです。

rootlessなら、操作できる範囲はそのユーザーのコンテナに限られます。rootfulの/run/podman/podman.sockを読み書きできる人は、ホストのroot相当の操作ができます。api実装でrootfulソケットに接続する構成は、Claude Codeに渡す権限としては重い構成です。

使えるツールと、できないこと

ツールは4カテゴリー13個です。

ネットワークやボリュームを作る・消す操作が必要なときは、docker network createのようなコマンドをBashツール経由で実行します。

引数の絞り込みにも注意が必要です。READMEのツール定義では、container_runが受け取るのはイメージ名・環境変数・ポートの対応(8080:80の形式)の3つで、コンテナ内で実行するコマンドやボリュームのマウントを指定する引数はありません。container_listの説明は、実行中のコンテナの情報を出力するというものです。image_buildのContainerfileは絶対パスで渡します。

一覧系の出力形式は--output-format(短縮-o)で選びます。既定は人が読む表形式のtextで、jsonも選べます。

コンテナを動かす側ではなく、クラスターの操作まで任せたい場合はKubernetes MCPサーバーの使い方の領分です。レジストリ側のイメージ検索はDocker Hub MCPサーバーが対応します。

HTTPモードで起動してClaude Codeから接続する

既定の通信はstdioで、Claude Codeがサーバーのプロセスを起動します。--portを付けると、サーバーが単独で待ち受けるHTTPモードになります。Streamable HTTPが/mcp、SSEが/sseです。

# 別のターミナルでサーバーを起動
podman-mcp-server --port 8080
 
# Claude Code側はHTTPトランスポートで追加
claude mcp add --transport http podman http://localhost:8080/mcp

--sse-portと--sse-base-urlは非推奨で、SSEだけの旧モードです。新しく設定するときは--portを使います。claude mcp add --transportにはstdio・sse・httpの3つがあり、--portで起動したサーバーにはhttpで/mcpを指します。

よくあるつまずき

接続はできているのにコンテナが見えない

見たいコンテナと別のソケットにつながっている可能性があります。ls $XDG_RUNTIME_DIR/podman/でrootless側のソケットがあるかを確かめ、あればCONTAINER_HOSTにそのパスを指定して、一覧の結果が変わるかを試します。

apiにしたいのにcliで動いている

Podmanを使っているのにpodman.socketを有効にしていない環境が典型です。--podman-impl=apiで固定すると、つながらない理由がエラーとして表に出ます。Docker Desktopだけの環境にはPodmanのソケットがないので、cliがdockerバイナリを呼ぶ構成が正しい動作です。

追加したのに別のプロジェクトでは見えない

claude mcp listを追加時とは別のディレクトリで実行してpodmanが出なければ、localスコープで追加されています。全プロジェクトで使うなら--scope userを付けて追加し直します。

バージョンアップでツール名が変わった

0.0系では後方互換性が保証されていません。スクリプトやCIからcontainer_runのようなツール名を前提に自動化しているなら、@latestのまま使い続けず、版を固定したうえで更新前にinspectorでツール一覧を比べます。

まとめ

個人のrootless環境なら、stdioで追加してCONTAINER_HOSTを指定する構成が出発点です。rootfulソケットしかない共有ホストでは、権限の重さを考えて--podman-impl=cliで固定する選択肢があります。0.0系なので、更新のたびにツール一覧を見直す前提で使います。

よくある質問

Claude DesktopやVS Codeでも同じサーバーを使えますか

READMEにはClaude Desktop、VS Code、Goose CLIの設定例があります。Claude Desktopでは、claude_desktop_config.jsonのmcpServersに次を足します。

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