ポーテナーMCP

カバレッジ

Portainer に何が起こっているのか尋ねたいと思ったことはありませんか?

さあ、今すぐ始めましょう！Portainer MCPは、AIアシスタントをPortainer環境に直接接続します。ユーザーや環境などのPortainerリソースを管理したり、DockerやKubernetesのコマンドをAI経由で直接実行して、より詳細な情報を取得したりできます。

ポーテナー-MCP-デモ

概要

Portainer MCPは、Portainer環境向けのモデルコンテキストプロトコル（MCP）の実装であり、現在開発中です。このプロジェクトは、Portainerのコンテナ管理機能をAIモデルやその他のサービスに接続するための標準化された方法を提供することを目的としています。

MCP（モデルコンテキストプロトコル）は、アプリケーションがLLM（大規模言語モデル）にコンテキストを提供する方法を標準化するオープンプロトコルです。USB-Cがデバイスと周辺機器を接続するための標準化された方法を提供するのと同様に、MCPはAIモデルをさまざまなデータソースやツールに接続するための標準化された方法を提供します。

この実装は、MCP プロトコルを通じて Portainer 環境データを公開することに重点を置いており、AI アシスタントやその他のツールが安全かつ標準化された方法でコンテナ化されたインフラストラクチャと対話できるようにします。

互換性と利用可能な機能の詳細については、 Portainer バージョンサポートとサポートされる機能のセクションを参照してください。

注: このプロジェクトは現在開発中です。

現在、Portainer 管理者 API トークンで動作するように設計されています。

インストール

Linux（amd64、arm64）およびmacOS（arm64）用のビルド済みバイナリは、最新リリースページからダウンロードできます。「Assets」セクションで、お使いのオペレーティングシステムとアーキテクチャに適したアーカイブを見つけてください。

**アーカイブをダウンロードします。**通常はリリースページから直接ダウンロードできます。または、 curlを使うこともできます。macOS (ARM64) バージョンv0.2.0の例を以下に示します。

# Example for macOS (ARM64) - adjust version and architecture as needed
curl -Lo portainer-mcp-v0.2.0-darwin-arm64.tar.gz https://github.com/portainer/portainer-mcp/releases/download/v0.2.0/portainer-mcp-v0.2.0-darwin-arm64.tar.gz

(Linux AMD64 バイナリもリリースページで入手できます。)

**（オプションですが推奨）チェックサムの検証：**まず、リリースページから対応する.md5チェックサムファイルをダウンロードします。macOS (ARM64) v0.2.0の例：

# Download the checksum file (adjust version/arch)
curl -Lo portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5 https://github.com/portainer/portainer-mcp/releases/download/v0.2.0/portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5
# Now verify (output should match the content of the .md5 file)
if [ "$(md5 -q portainer-mcp-v0.2.0-darwin-arm64.tar.gz)" = "$(cat portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5)" ]; then echo "OK"; else echo "FAILED"; fi

(Linux の場合は、 md5sum -c <checksum_file_name>.md5を使用できます) 検証コマンドで「OK」が出力された場合、ファイルはそのままです。

アーカイブを抽出します:

# Adjust the filename based on the downloaded version/OS/architecture
tar -xzf portainer-mcp-v0.2.0-darwin-arm64.tar.gz

これによりportainer-mcp実行ファイルが抽出されます。

**実行可能ファイルを移動します。**実行可能ファイルを$PATH内の場所 (例: /usr/local/bin ) に移動する、または以下の構成手順のためにその場所をメモしておきます。

使用法

Claude Desktop の場合は次のように設定します。

{
    "mcpServers": {
        "portainer": {
            "command": "/path/to/portainer-mcp",
            "args": [
                "-server",
                "[IP]:[PORT]",
                "-token",
                "[TOKEN]",
                "-tools",
                "/tmp/tools.yaml"
            ]
        }
    }
}

[IP] 、 [PORT] 、 [TOKEN]をPortainerインスタンスに関連付けられたIP、ポート、APIアクセストークンに置き換えます。

[!NOTE] デフォルトでは、ツールはバイナリと同じディレクトリにある「tools.yaml」を探します。ファイルが存在しない場合は、デフォルトのツール定義でそこに作成されます。特に、作業ディレクトリへの書き込み権限が制限されているClaudeなどのAIアシスタントを使用する場合は、上記のようにこのパスを変更する必要がある場合があります。

ツールのカスタマイズ

デフォルトでは、ツール定義はバイナリに埋め込まれます。ツールファイルがまだ存在しない場合、アプリケーションはデフォルトの場所にツールファイルを作成します。

-toolsフラグを使用してカスタムツールファイルパスを指定することにより、ツール定義をカスタマイズできます。

{
    "mcpServers": {
        "portainer": {
            "command": "/path/to/portainer-mcp",
            "args": [
                "-server",
                "[IP]:[PORT]",
                "-token",
                "[TOKEN]",
                "-tools",
                "/path/to/custom/tools.yaml"
            ]
        }
    }
}

デフォルトのツールファイルは、ソースコード内のinternal/tooldef/tools.yamlで参照できます。ツールとそのパラメータの説明を変更することで、AIモデルによるツールの解釈方法と使用方法を変更することができます。また、使用したくないツールを削除することも可能です。

[!警告] ツール名またはパラメータ定義 (説明以外) を変更しないでください。変更すると、ツールが適切に登録されなくなり、正しく機能しなくなります。

読み取り専用モード

セキュリティを重視するユーザーのために、アプリケーションを読み取り専用モードで実行できます。このモードでは読み取り操作のみが実行可能となり、Portainerリソースへの変更が完全に防止されます。

読み取り専用モードを有効にするには、コマンド引数に-read-onlyフラグを追加します。

{
    "mcpServers": {
        "portainer": {
            "command": "/path/to/portainer-mcp",
            "args": [
                "-server",
                "[IP]:[PORT]",
                "-token",
                "[TOKEN]",
                "-read-only"
            ]
        }
    }
}

読み取り専用モードを使用する場合:

AIモデルでは読み取りツール（リスト、取得）のみが利用可能になります
すべての書き込みツール（作成、更新、削除）が読み込まれていません
Dockerプロキシリクエストツールがロードされていません
Kubernetes プロキシリクエストツールがロードされていません

Portainer バージョンサポート

このツールは、特定のバージョンのPortainerをサポートするために固定されています。アプリケーションは起動時にPortainerサーバーのバージョンを検証し、必要なバージョンと一致しない場合は失敗します。

ポーテナーMCPバージョン	サポートされているPortainerバージョン
0.1.0	2.28.1
0.2.0	2.28.1
0.3.0	2.28.1
0.4.0	2.29.2
0.4.1	2.29.2
0.5.0	2.30.0

サポートされている機能

次の表は、MCP ツールを通じて現在 (最新バージョン) サポートされている操作を示しています。

リソース	手術	説明	サポートされているバージョン
環境
	リスト環境	利用可能なすべての環境を一覧表示する	0.1.0
	環境タグの更新	環境に関連付けられたタグを更新する	0.1.0
	環境ユーザーアクセスの更新	環境のユーザーアクセスポリシーを更新する	0.1.0
	環境チームアクセスの更新	環境のチームアクセスポリシーを更新する	0.1.0
環境グループ（エッジグループ）
	環境グループの一覧	利用可能なすべての環境グループを一覧表示する	0.1.0
	環境グループの作成	新しい環境グループを作成する	0.1.0
	環境グループ名の更新	環境グループの名前を更新する	0.1.0
	環境グループ環境の更新	グループに関連付けられた環境を更新する	0.1.0
	環境グループタグの更新	グループに関連付けられたタグを更新する	0.1.0
アクセスグループ (エンドポイントグループ)
	アクセスグループの一覧	利用可能なすべてのアクセスグループを一覧表示する	0.1.0
	アクセスグループの作成	新しいアクセスグループを作成する	0.1.0
	アクセスグループ名の更新	アクセスグループの名前を更新する	0.1.0
	アクセスグループユーザーアクセスの更新	アクセスグループのユーザーアクセスを更新する	0.1.0
	UpdateAccessGroupTeamAccesses	アクセスグループのチームアクセスを更新する	0.1.0
	アクセスグループに環境を追加	アクセスグループに環境を追加する	0.1.0
	アクセスグループから環境を削除する	アクセスグループから環境を削除する	0.1.0
スタック（エッジスタック）
	リストスタック	利用可能なスタックをすべて一覧表示する	0.1.0
	スタックファイルを取得	特定のスタックのコンポーズファイルを取得する	0.1.0
	スタックの作成	新しいDockerスタックを作成する	0.1.0
	アップデートスタック	既存のDockerスタックを更新する	0.1.0
タグ
	環境タグの一覧	利用可能なすべての環境タグを一覧表示する	0.1.0
	環境タグの作成	新しい環境タグを作成する	0.1.0
チーム
	リストチーム	利用可能なすべてのチームを一覧表示する	0.1.0
	チームを作成	新しいチームを作成する	0.1.0
	チーム名の更新	チーム名を更新する	0.1.0
	チームメンバーの更新	チームのメンバーを更新する	0.1.0
ユーザー
	リストユーザー	利用可能なユーザーをすべて一覧表示する	0.1.0
	ユーザー��更新	既存のユーザーを更新する	0.1.0
	設定を取得	Portainerインスタンスの設定を取得する	0.1.0
ドッカー
	Dockerプロキシ	あらゆるDocker APIリクエストをプロキシする	0.2.0
Kubernetes
	Kubernetesプロキシ	あらゆるKubernetes APIリクエストをプロキシする	0.3.0

発達

コード統計

リポジトリには、 clocツールを使用して Go ソースファイルのコード行数やその他のメトリクスを計算するヘルパースクリプトcloc.shが含まれています。事前にclocをインストールする必要がある場合があります（例： sudo apt install clocまたはbrew install cloc ）。

リポジトリルートからスクリプトを実行して、デフォルトのサマリー出力を表示します。

./cloc.sh

特定のメトリックを取得するために使用できるフラグの詳細については、 cloc.shスクリプト内のコメントヘッダーを参照してください。

トークンカウント

現在のツール定義がプロンプトで消費するトークンの数を見積もるには、提供されている Go プログラムとシェルスクリプトを使用して、Anthropic API のトークンカウントエンドポイントを照会します。

1. ツールのJSONを生成します。

まず、 token-count Goプログラムを使って、YAMLツール定義をAnthropic APIに必要なJSON形式に変換します。リポジトリのルートから以下を実行します。

# Replace internal/tooldef/tools.yaml with your YAML file if different
# Replace .tmp/tools.json with your desired output path
go run ./cmd/token-count -input internal/tooldef/tools.yaml -output .tmp/tools.json

このコマンドは、指定された入力 YAML ファイルからツール定義を読み取り、ツールの JSON 配列 ( name 、 description 、 input_schemaを含む) を指定された出力ファイルに書き込みます。

2. Anthropic API にクエリを実行します。

次に、 token.shスクリプトを使用して、これらのツール定義とサンプルメッセージを Anthropic API に送信します。この手順では Anthropic API キーが必要になります。

# Ensure you have jq installed
# Replace sk-ant-xxxxxxxx with your actual Anthropic API key
# Replace .tmp/tools.json with the path to the file generated in step 1
./token.sh -k sk-ant-xxxxxxxx -i .tmp/tools.json

スクリプトは、Anthropic API からの JSON 応答を出力します。これには、提供されたツールの推定トークン数と、 usage.input_tokensフィールドにサンプルメッセージが含まれます。

このプロセスは、言語モデルに提供されるツールセットに関連付けられたトークンのコストを理解するのに役立ちます。

Portainer MCP