Portainer MCP

Portainer MCP

FastMCP を介して Portainer の OpenAPI 仕様から生成された、Portainer 用 MCP サーバーです。

重要

Portainer で LLM を使用する方法として、Portainer MCP はサポート対象ではなくなりました。 現在は、Portainer Business Edition のお客様（無料の 3 ノードライセンスを含む）が利用できる Portainer Command をご利用ください。

このサーバーは、引き続き利用したい方のために現状のまま提供されていますが、サポート、保証、SLA はありません。また、本番環境での利用は推奨されません。このリポジトリは将来的にアーカイブされる可能性があります。

概要

この MCP サーバーは Portainer REST API を MCP ツールとして公開します。環境の一覧表示と調査、GitOps ワークフローの管理、Docker および Kubernetes リソースのトラブルシューティングが可能です。また、各環境の基盤となる Docker API および K8s API へのリクエストのプロキシにも対応しています。

MCP サーバーのマイナーバージョンは、Portainer インスタンスのマイナーバージョンに合わせてください。たとえば、Portainer 2.45.x には MCP サーバー 2.45.x を使用します。詳細はバージョンの互換性をご覧ください。

想定される用途

Portainer MCP は、評価、ホームラボ、その他の非本番環境での利用を想定しています。稼働時間、セキュリティ態勢、データの完全性が重要となるビジネス、本番、その他の環境ではサポートされません。SLA はなく、問題への対応も保証されず、今後の機能開発やロードマップの確約もありません。実行する場合は、ご自身でサポートすることになります。

Portainer で LLM をサポート対象の方法で利用するには、Portainer Command をご利用ください（無料の 3 ノードライセンスを含む Business Edition）。

はじめに

MCP サーバーは、さまざまなデプロイ方法に対応しています。

• uvx を使ってローカルで実行する
• MCP バンドルとしてインストールする
• コンテナとしてデプロイする

MCP の機能をローカルで試すには uvx 方式または MCP バンドルを使用し、チームでのデプロイ構成では、インフラストラクチャ内にコンテナとしてデプロイしてください。

メモ

どちらの方法でも API キーが必要となるため、MCP を使用する前に、Portainer の My Account → Access tokens で API キーを生成してください。

MCP バンドル（ワンクリックインストール）

MCP サーバーをローカルで手軽に試す方法です。クライアントは MCP バンドルに対応している必要があります。

1. 最新リリースから、お使いのプラットフォーム用の自己完結型 .mcpb バンドルを取得します
2. ダブルクリックしてインストールします
3. Portainer の URL と API キーを入力します。

単一ユーザー（uvx を使った stdio）

MCP サーバーをローカルでテストするもう一つの方法です。お使いのマシン上で stdio プロセスとして実行され、Portainer インスタンスに直接接続します。

メモ

uv がインストールされ、PATH から利用できる必要があります。 uv のインストール手順をご覧ください。

Portainer インスタンスで自己署名 TLS 証明書を使用している場合は、PORTAINER_TLS_VERIFY=0 を設定してください。

Claude Code に登録します。

claude mcp add portainer \
  -e PORTAINER_URL=https://portainer.example.com \
  -e PORTAINER_API_KEY=ptr_xxxxxxxxxxxxxxxx \
  -- uvx --from "mcp-portainer~=2.45.0" mcp-portainer

その他のクライアントについては、 docs/distribution/をご覧ください。

チームデプロイ（コンテナ）

複数のユーザーが MCP 経由で Portainer インスタンスを操作できる方法です。インフラストラクチャ内にコンテナとしてデプロイし、ユーザーは各自のワークステーションから HTTPS 経由でアクセスします。共有シークレットによって MCP サーバーへのアクセスを制限し、各クライアントはそれぞれの Portainer API キーも転送するため、各ユーザーは自分の Portainer ID で操作できます。

重要

ゲート用シークレットと各ユーザーの Portainer API キーは、どちらも通信経路上で送信されます。コンテナをデプロイする際は、使用するトランスポートのセキュリティ方針を明示する必要があります。TLS 証明書を用意するか、TLS 終端リバースプロキシの構成を証明するか、または平文通信を明示的に選択してください。

平文通信は、意図的に選択する危険な方法です。以下の 3 つのオプションを参照してください。

この MCP サーバーをパブリックインターネットに公開することは推奨されません。TLS プロキシの背後であっても、プライベートインフラストラクチャ内にホストしてください。

以下で、さまざまなデプロイシナリオの詳細を説明します。いずれのシナリオでも、次の点に注意してください。

• ユーザーが MCP にアクセスする際に使用するホスト名または IP アドレスを PORTAINER_MCP_ALLOWED_HOSTS に設定してください。設定しない場合、DNS リバインディング対策の許可リストによりリクエストが 421 で拒否されます。
• HTTP モードでは PORTAINER_MCP_AUTH_TOKEN が必須です。これはユーザーに配布する共有ゲート用シークレットで、MCP クライアントは Authorization ヘッダーを使って送信します。このトークンが許可するのはリクエストの通過のみです。各ユーザーに許可される操作は、それぞれの Portainer API キーによって決まります。例外として、Authorization ヘッダーを管理する ID 対応プロキシの背後で使用する場合は、代わりに PORTAINER_MCP_TRUST_PROXY_AUTH=1 を使用してください（オプション D を参照）。

オプション A - 証明書を用意する

メモ

自己署名証明書を使用すると、サーバーから警告が表示されます。プライベート CA 証明書では警告は表示されませんが、いずれの場合も、MCP クライアントが証明書を受け入れるように設定するには、いくつかの手順が必要になることがあります。

独自の TLS 証明書を使用するようにコンテナをデプロイします。

TOKEN=$(openssl rand -hex 32)
docker run -d --name portainer-mcp -p 17717:17717 \
	-v /etc/portainer-mcp/tls:/tls:ro \
	-e PORTAINER_URL=https://portainer.example.com \
	-e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \
	-e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com:17717 \
	-e PORTAINER_MCP_TLS_CERT=/tls/cert.pem \
	-e PORTAINER_MCP_TLS_KEY=/tls/key.pem \
	portainer/portainer-mcp:2.45

次に、クライアントを接続します。

claude mcp add portainer --transport http https://mcp.example.com:17717/mcp \
  --header "Authorization: Bearer <gate-token>" \
  --header "X-Portainer-API-Key: <ptr_user_key>"

オプション B - TLS 終端リバースプロキシ

メモ

MCP コンテナの前段にリバースプロキシを置く場合、コンテナのポートを公開しないでください。アクセスできるのはプロキシのみとしてください。

PORTAINER_MCP_FORWARDED_ALLOW_IPS には、固定されている場合はプロキシの正確な IP を使用してください。

プロキシが元の Host ヘッダーと X-Forwarded-Proto: https ヘッダーを転送することを確認してください。

プロキシを用意し、コンテナの前段に TLS 終端プロキシを設定します。

TOKEN=$(openssl rand -hex 32)
docker run -d --name portainer-mcp \
	-e PORTAINER_URL=https://portainer.example.com \
	-e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \
	-e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com \
	-e PORTAINER_MCP_TRUST_PROXY_TLS=1 \
	-e PORTAINER_MCP_FORWARDED_ALLOW_IPS=172.18.0.0/16 \
	portainer/portainer-mcp:2.45

次に、クライアントを接続します。

claude mcp add portainer --transport http https://mcp.example.com/mcp \
  --header "Authorization: Bearer <gate-token>" \
  --header "X-Portainer-API-Key: <ptr_user_key>"

オプション C - 平文 HTTP

警告

信頼できるプライベートネットワーク内でのデプロイ以外で使用することは推奨されません。

PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 フラグを使って、HTTP のみでサーバーを起動します。

TOKEN=$(openssl rand -hex 32)
docker run -d --name portainer-mcp -p 17717:17717 \
	-e PORTAINER_URL=https://portainer.example.com \
	-e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \
	-e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com:17717 \
	-e PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 \
	portainer/portainer-mcp:2.45

次に、クライアントを接続します。

claude mcp add portainer --transport http http://mcp.example.com:17717/mcp \
  --header "Authorization: Bearer <gate-token>" \
  --header "X-Portainer-API-Key: <ptr_user_key>"

オプション D - アイデンティティ対応プロキシ（MCP OAuth）

ユーザーが MCP OAuth フローに対応したアイデンティティ対応プロキシ（MCP サーバーモードの Pomerium など）を通じて認証する場合、プロキシは独自のアクセストークンを発行し、Authorization ヘッダーを所有します。PORTAINER_MCP_AUTH_TOKEN の代わりに、信頼プロキシ認証の設定を宣言します。

メモ

オプション B と同じルールが適用されます。コンテナポートを公開せず（プロキシのみがアクセスできるようにし）、プロキシが元の Host ヘッダーと X-Forwarded-Proto: https ヘッダーを転送するようにしてください。

各リクエストには、呼び出し元自身の Portainer API キーを X-Portainer-API-Key に含める必要があります。プロキシからユーザーごとに挿入するか、各クライアントから送信してください。プロキシは誰がアクセスできるかを制御し、Portainer キーは何ができるかを決定します。

docker run -d --name portainer-mcp \
	-e PORTAINER_URL=https://portainer.example.com \
	-e PORTAINER_MCP_TRUST_PROXY_AUTH=1 \
	-e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com \
	-e PORTAINER_MCP_TRUST_PROXY_TLS=1 \
	-e PORTAINER_MCP_FORWARDED_ALLOW_IPS=172.18.0.0/16 \
	portainer/portainer-mcp:2.45

ゲートトークンは設定されていません。リクエストは、プロキシによる証明（PORTAINER_MCP_FORWARDED_ALLOW_IPS から到着する必要があります。これは信頼境界として引き継がれ、* を指定すると起動が拒否されます）と、呼び出し元の検証済み Portainer キーによって許可されます。MCP サーバーがプロキシではなく自身で TLS を終端する場合は、2 つの TRUST_PROXY_TLS／FORWARDED_ALLOW_IPS の行の代わりに PORTAINER_MCP_TRUSTED_PROXY_AUTH_IPS=<proxy ip/cidr> を設定してください。設定ルール全体については、docs/configuration.md を参照してください。

MCP サーバーの機能の制限と拡張

MCP サーバーでは、次の機能がデフォルトで有効になっています。

• Portainer の基本操作のサポート（設定、バージョン、環境など）
• Docker 操作のサポート
• Kubernetes 操作のサポート
• Docker および Kubernetes のプロキシサポート
• 環境変数の値のマスキング（デフォルトで有効）

これらの機能を制限または拡張する方法については、docs/profiles.md を参照してください。

バージョンの互換性

MCP サーバーのマイナーバージョンを Portainer のマイナーバージョンに合わせてください。 メジャーおよびマイナーバージョンは、組み込み仕様が対象とする Portainer API のバージョンを示します。

サーバーバージョン	Portainer（CE / EE）
2.45.x	2.45.x
2.44.x	2.44.x
2.43.x	2.43.x
2.42.x	2.42.x
2.41.x	2.41.x

バージョンポリシーの詳細については、docs/versioning.md を参照してください。

設定

MCP サーバーでは、次のようなさまざまな機能を設定できます。

• 特定のプロファイル設定に基づいて、使用するツールのセットを有効にする
• 対象とするタグを追加指定して API の対応範囲を広げる
• 読み取り専用の機能のみを公開する
• プロキシ機能を無効にする
• トランスポート機能を調整し、TLS の設定を構成する
• ログを設定する

MCP サーバーの設定の詳細については、docs/configuration.md を参照してください。

サポートを受ける

Portainer MCP には公式のサポート窓口がありません。GitHub に Issue を登録できますが、登録しても、プロジェクトに回答、トリアージ、修正の義務が生じることはありません。

Portainer MCP にサポート対象のバージョンはありません。現状有姿で提供され、保証はありません。