panelica-mcp

Name: panelica-mcp
Author: Panelica

ローカル

github.com/Panelicaクラウド・インフラ23 日前に更新

リポジトリ

panelica-mcp について

AI クライアントから Panelica のホスティングパネルを管理する MCP サーバーです。パネルの API 仕様からツール一覧を作成し、HMAC-SHA256 署名付きでリクエストを転送します。

主な機能

01ドメイン、DNS、SSL、データベースの管理
02メール、FTP、バックアップ、サーバーリソースの操作
03ライブ API 仕様からツール一覧を生成
04ツールセットごとの登録ツール選択
05ツールの検索と詳細表示
06API キーのスコープに応じたエラー説明

活用シーン

01AI クライアントからドメインと DNS を設定
02SSL 証明書の発行とデータベース管理
03サーバーのサービスとリソースを確認
04既定セット以外のツールを検索して呼び出す

MCP 対応

stdio 経由で MCP クライアントに Panelica External API のツールを公開します。ライブまたは同梱の API 仕様を読み込み、ツール呼び出しを HMAC-SHA256 署名付き HTTP リクエストに変換します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "panelica-panelica": {
      "command": "npx",
      "args": [
        "-y",
        "panelica-mcp"
      ],
      "env": {
        "PANELICA_BASE_URL": "<PANELICA_BASE_URL>",
        "PANELICA_API_KEY": "<PANELICA_API_KEY>",
        "PANELICA_API_SECRET": "<PANELICA_API_SECRET>"
      }
    }
  }
}

起動コマンドnpx -y panelica-mcp

設定が必要な環境変数

PANELICA_BASE_URLExternal API base URL of your panel, e.g. https://panel.example.com:8443/api/external

PANELICA_API_KEYシークレットAPI key from the panel (Developer -> API). Grant only the scopes the assistant needs.

PANELICA_API_SECRETシークレットAPI secret paired with the key; used locally for HMAC-SHA256 request signing.

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

npmpanelica-mcp0.5.2stdio

ツール

掲載時のツール一覧 · 2 週間前に更新

パラメーター	型	必須	説明
limit	integer	いいえ	結果の最大数（デフォルト 10、最大 50）
query	string	はい	キーワード。例：「dns records」「wordpress update」「ssl issue」

詳細

Panelica MCP Server

Panelica のホスティングパネルを、自然な英語で操作できます。ドメインの割り当て、SSL 証明書の発行、データベースの作成、サービスの再起動などを、Claude Desktop、Cursor、ChatGPT、その他の Model Context Protocol クライアントから実行できます。

404 個のツールで、アカウント、ドメイン、DNS、SSL、メール、MySQL、FTP、セキュリティ、バックアップ、サーバーリソースなど、External API の全機能を利用できます。

仕組み

+----------------+         stdio JSON-RPC          +-------------------+
|  MCP client    |  <----------------------------> |  panelica-mcp     |
|  (Claude, ...) |                                 |  (this package)   |
+----------------+                                 +---------+---------+
                                                             |
                                          HTTPS + HMAC-SHA256|
                                            X-API-Key        |
                                            X-Timestamp      |
                                            X-Signature      |
                                                             v
                              +------------------------------+------------------------------+
                              |  https://<panel-host>:8443/api/external/v1/...               |
                              |  nginx reverse proxy on the panel host                       |
                              |  (TLS termination + path rewrite: /api/external/X -> /X)     |
                              +------------------------------+------------------------------+
                                                             |
                                       127.0.0.1:3002 plain  |
                                                             v
                                            +----------------+-----------------+
                                            |  external-server (HMAC verify)   |
                                            +----------------+-----------------+
                                                             |
                                                             v
                                            +----------------+-----------------+
                                            |  Panelica panel + Linux services |
                                            +----------------------------------+

panelica-mcp は、薄くステートレスなアダプターです。

MCP クライアントが stdio 経由でバイナリを起動します。
起動時にサーバーは、お使いのパネルから <PANELICA_BASE_URL>/v1/api-spec を取得し、それに基づいてツール一覧を作成します（デフォルトでは最新のカタログを使用します）。パネルに接続できない場合は、同梱の tools/tools.json スナップショットにフォールバックします。常にスナップショットを使うには、PANELICA_LIVE_SPEC=0 を設定してください。
クライアントがツール一覧を要求すると、一覧とともにサーバー指示（ID、スコープ、レスポンスのエンベロープ、エラー、レート制限の仕組み、およびワークフローのレシピ）が返されます。これらは同じカタログから生成されます。アシスタントが把握している内容をご覧ください。
クライアントがツールを呼び出すと、サーバーは対応する HTTP リクエストを作成し、ローカルの PANELICA_API_SECRET を使って HMAC-SHA256 で署名してから、パネルに転送します。
HTTP レスポンスはツールの結果としてクライアントに返されます。呼び出しに失敗した場合は、ステータスコードだけでなく、次に何をすべきか（不足しているスコープ、誤った ID、レート制限のリセットなど）の説明が返されます。

データはキャッシュされず、テレメトリも送信されません。また、シークレットが MCP サーバーの実行マシンから外部に送信されることはありません。

要件

Panelica パネルが稼働していること（バージョン 1.0.193 以降を推奨。External API の仕様は 1.0.180 以降で安定しています）。
panelica-mcp を実行するマシンから、ポート 8443 でパネル UI に HTTPS 接続できること。これはブラウザーですでに使用しているポートと同じで、追加のファイアウォール設定は不要です。
そのマシンに、次のいずれかのランタイムがあること：
- npm でインストールする場合は Node.js ≥ 20
- コンテナーを使用する場合は Docker

パネルのホスト自体に何かをインストールする必要はありません。また、内部ポート 3002 をパブリックインターネットに公開する必要もありません。

インストール

MCP クライアントの設定に合わせて選んでください。どの方法でも同じ stdio バイナリが作成されます。好みのサンドボックスモデルに合わせて選択してください。

オプション A — npm（推奨）

npm install -g panelica-mcp

または、インストールせずに実行します（MCP クライアントが npx を起動します）。

npx -y panelica-mcp

-y フラグは、npm の「初回実行時にインストール」プロンプトを非対話形式で承認します。これは MCP クライアントで必要です。

オプション B — Docker

ビルド済みのイメージは、リリースごとに GitHub Container Registry に公開されます。

docker pull ghcr.io/panelica/panelica-mcp:latest

MCP クライアントの設定から実行します。

{
  "command": "docker",
  "args": [
    "run", "--rm", "-i",
    "-e", "PANELICA_BASE_URL",
    "-e", "PANELICA_API_KEY",
    "-e", "PANELICA_API_SECRET",
    "ghcr.io/panelica/panelica-mcp:latest"
  ],
  "env": {
    "PANELICA_BASE_URL": "https://your-panel-host:8443/api/external",
    "PANELICA_API_KEY":  "pk_...",
    "PANELICA_API_SECRET": "sk_..."
  }
}

-i は stdin を接続したままにし、MCP クライアントがコンテナーと通信できるようにします。 --rm は、クライアントが切断したときにコンテナーを削除します。

オプション C — ソースからビルド

git clone https://github.com/Panelica/panelica-mcp.git
cd panelica-mcp
npm install
npm run build
node dist/index.js          # speaks MCP over stdio

パネルの稼働中の API 仕様から tools/tools.json を再生成するには：

PANELICA_SPEC_URL="https://your-panel:8443/api/external/v1/api-spec" npm run rebuild-tools

設定

必要な値は 3 つです。到達可能なベース URL、API キー、API シークレットです。

1. 適切なベース URL を選ぶ

Panelica の external-server プロセスは 127.0.0.1:3002 でリッスンし、パネルの nginx は 8443 で /api/external/... をこのプロセスにリバースプロキシします。nginx は転送前に /api/external プレフィックスを取り除くため、HMAC 署名の計算対象となるパスとバックエンドが受け取るパスは、どちらも最終的に /v1/... になります。これにより、追加設定なしでエンドツーエンドの署名が一致します。

適切な PANELICA_BASE_URL は、panelica-mcp を実行する場所によって異なります。

シナリオ	推奨する `PANELICA_BASE_URL`
ノート PC 上の MCP クライアントからリモートサーバー上のパネルに接続する	`https://<panel-host>:8443/api/external`
MCP クライアントとパネルが同じマシン上にある	`http://127.0.0.1:3002`

ポート 3002 をパブリックインターネットに公開しないでください。デフォルトのインストールではすべてのインターフェースでリッスンしますが、ファイアウォールで保護するか、8443 のリバースプロキシ経由でのみアクセスすることを想定しています。

お使いのマシンからプロキシを確認します。

curl -sk https://<panel-host>:8443/api/external/health
# {"status":"ok"} or similar

TLS エラーが発生した場合は、パネルの自己署名証明書が原因です。クライアント側で検証を無効にするのではなく、パネルに正規の証明書をインストールしてください（パネル UI → Settings → SSL）。

2. パネルで API キーを生成する

root または API キーを管理する権限を持つアカウントでパネルにサインインします。
Settings → API Keys → Generate API Key に移動します。
MCP サーバーに付与するスコープを選択します。読み取り専用のアシスタントであれば、*:read で十分です（パネル 1.0.528 以降。古いパネルでは個別の <area>:read スコープが必要です）。完全な自動化には *:write と *:delete も付与するか、*:* を指定してください。このサーバーの各ツールの description に、必要なスコープが記載されています。
key（pk_... のような形式）と secret（sk_... のような形式）の両方をコピーします。シークレットは一度しか表示されません。パスワードマネージャーに保存してください。

3. curl で認証情報を検証する

MCP クライアントを接続する前に、認証情報がエンドツーエンドで機能することを確認します。

export PANELICA_BASE_URL=https://your-panel-host:8443/api/external
export PANELICA_API_KEY=pk_xxxxxxxx
export PANELICA_API_SECRET=sk_xxxxxxxx

TS=$(date +%s)
# Signature is over METHOD + PATH + TIMESTAMP + BODY. The path is the
# backend-visible path (/v1/...) — NOT the /api/external/ prefix that nginx
# strips before forwarding. panelica-mcp does this automatically.
SIG=$(printf "GET/v1/api-keys${TS}" \
  | openssl dgst -sha256 -hmac "$PANELICA_API_SECRET" -hex | awk '{print $2}')

curl -sk "$PANELICA_BASE_URL/v1/api-keys" \
  -H "X-API-Key:   $PANELICA_API_KEY" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

API キーの一覧を含む JSON が返されます。よくある 401 応答は次のとおりです。

`error.code`	考えられる原因
`MISSING_API_KEY` / `MISSING_TIMESTAMP` / `MISSING_SIGNATURE`	ヘッダーが空です。curl のフラグを再確認してください
`INVALID_KEY_FORMAT`	`PANELICA_API_KEY` の値の形式が正しくありません
`INVALID_TIMESTAMP`	ローカル時計が 5 分以上ずれています。NTP を同期してください
`INVALID_SIGNATURE`	シークレットが間違っているか、署名したパスに `/api/external/` が含まれています（含めてはいけません。バックエンドが受け取る前に nginx が取り除きます）

4. 任意の環境変数

変数	デフォルト	効果
`PANELICA_TOOLSETS`	`core`	直接登録するツールを指定します。詳しくはツールセットをご覧ください
`PANELICA_LIVE_SPEC`	`1`	起動時にパネルの `/v1/api-spec` からカタログを構築します。`0` = 同梱スナップショットのみ
`PANELICA_SPEC_TIMEOUT_MS`	`8000`	スナップショットへのフォールバック前のライブ仕様取得タイムアウト
`PANELICA_TIMEOUT_MS`	`30000`	呼び出しごとの HTTP タイムアウト
`PANELICA_MAX_RESULT_CHARS`	`60000`	大きなリスト結果は先頭の項目だけに切り詰められ、`_truncated` の注記が付加されます。これによりクライアントのコンテキストが過剰に消費されるのを防ぎます
`PANELICA_STARTUP_PROBE`	`1`	起動時に一度 `GET /v1/me` を呼び出し、説明文にキーのスコープを記載します。`0` にするとスキップします

MCP クライアントに接続する

Claude Code（コマンド 1 つ）

claude mcp add panelica \
  -e PANELICA_BASE_URL=https://your-panel:8443/api/external \
  -e PANELICA_API_KEY=pk_... \
  -e PANELICA_API_SECRET=sk_... \
  -- npx -y panelica-mcp

これで完了です。「ドメインを一覧表示して」や「example.com 用のデータベースを作成して」と Claude Code に依頼すると、スコープ付き API キーを使ってパネルを操作します。

Claude Desktop

Claude Desktop の設定を編集します。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux（Claude Desktop ベータ版）: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "panelica": {
      "command": "npx",
      "args": ["-y", "panelica-mcp"],
      "env": {
        "PANELICA_BASE_URL":   "https://your-panel-host:8443/api/external",
        "PANELICA_API_KEY":    "pk_...",
        "PANELICA_API_SECRET": "sk_..."
      }
    }
  }
}

保存したら、Claude Desktop を完全に終了して（ウィンドウを閉じるだけではなく、終了してください）、再度開きます。新しいチャットでは、panelica が「37 tools available」（コアセットと 3 つのメタツール）を備えた接続済みの MCP サーバーとして表示されます。488 個すべてを使うには PANELICA_TOOLSETS=all を設定してください。

Cursor

Settings → MCP → Add new serverで設定します。

{
  "panelica": {
    "command": "npx",
    "args": ["-y", "panelica-mcp"],
    "env": {
      "PANELICA_BASE_URL":   "https://your-panel-host:8443/api/external",
      "PANELICA_API_KEY":    "pk_...",
      "PANELICA_API_SECRET": "sk_..."
    }
  }
}

OpenAI Codex CLI

~/.codex/config.toml に追加します。

[mcp_servers.panelica]
command = "npx"
args = ["-y", "panelica-mcp"]

[mcp_servers.panelica.env]
PANELICA_BASE_URL = "https://your-panel:8443/api/external"
PANELICA_API_KEY = "pk_..."
PANELICA_API_SECRET = "sk_..."

Continue.dev、Cline、Zed

stdio コマンドを受け付ける MCP 対応エディターなら、どれも同じ方法で動作します。npx -y panelica-mcp（またはビルド済みの dist/index.js の絶対パス）と 3 つの環境変数を指定してください。

汎用 stdio クライアント

PANELICA_BASE_URL=https://your-panel-host:8443/api/external \
PANELICA_API_KEY=pk_... \
PANELICA_API_SECRET=sk_... \
panelica-mcp

プロセスは stdin/stdout 経由で MCP JSON-RPC を通信します。まず initialize リクエストを送り、続けて tools/list、次に tools/call を送信してください。

ツールセット — クライアントに表示される内容

MCP クライアントにはツール数の上限があります。Cursor はすべてのサーバーを合わせてアクティブなツールを約 40 個までに制限し、残りを通知なく除外します。また、登録されたツールはどれも、各ターンでプロンプトトークンを消費します。そのため、デフォルトではサーバーはコンパクトな core セット（普段使いのツール 34 個：アカウント、ドメイン、DNS、SSL、データベース、メール、FTP、バックアップ、サーバーのステータス／サービス、WordPress、Docker、プラン）と、カタログ全体にアクセスできる 3 つのメタツールを登録します。

ツール	機能
`panelica_find_tools`	カタログ内のすべてのツールをキーワード検索します。名前、HTTP ルート、パラメーター、本文フィールド、および各ツールの戻り値を返します
`panelica_describe_tool`	1 つのツールの詳細をすべて表示します。出所情報を含むすべてのパラメーター、本文フィールド（型、必須かどうか）、レスポンスのエンベロープとそのデータフィールドを確認できます
`panelica_call`	引数を指定して、カタログ内の任意のツールを名前で実行します（同じスコープ付きの HMAC 署名クライアントを使用）

PANELICA_TOOLSETS（カンマ区切り、複数指定した場合は和集合）でセットを選択します。

値	登録されるツール
`core`（デフォルト）	34 個 + メタツール 3 個
`all`	カタログ内のすべてのツール + メタツール 3 個（0.3 より前の動作。Claude Code／Claude Desktop での使用に適しています）
`none`	メタツール 3 個のみ
カテゴリのスラッグ。例：`domains,dns,ssl,git,docker,file_manager,laravel_apps,node_js_apps,python_apps,logs`	指定したカテゴリ（`core` を含めた場合は `core` も追加）

カタログ内にあるものの登録されていないツールへの直接呼び出しも受け付けます。そのため、panelica_find_tools でツール名を取得したクライアントは、どちらの方法でも呼び出せます。

アシスタントが把握していること

400 個のツール名しか見えないアシスタントは、ID を推測し、403 を再試行し、レスポンスを読み違えます。panelica-mcp は代わりに API を「熟知」させます。以下はすべてカタログから生成されるため、パネルに存在しないパスを案内することはありません。

サーバーの指示（initialize 時に送信されるため、すべてのクライアントがモデルのコンテキストに挿入します）：呼び出しの仕組み、すべての ID はリスト取得の呼び出しから得られる UUID であること、ユーザーは アカウント と呼ばれること、{"status":"success","data":…} エンベロープ、ページ分割のないリスト、各エラークラスの意味と対処法、スコープの種類、件数付きのカテゴリーマップ、変更・破壊的ツールの安全ルール、およびすべてのステップがカタログに存在する場合にのみ含まれるワークフローの手順。
キーを最初に確認。 起動時にサーバーは GET /v1/me を 1 回呼び出し、保持しているキー、そのスコープ、ティア、有効期限をモデルに伝えます。そのため、読み取り専用キーは読み取り専用として通知され、スコープ外のツールは試行されず、追加すべきスコープとともに拒否されます。認証情報が拒否された場合は、最初のツール呼び出しより前に指示内で報告されます。（PANELICA_STARTUP_PROBE=0 でプローブを無効にできます。）
コードが適用するスコープ。 新しいパネルでは、手書きのドキュメントではなくミドルウェアチェーンから必要なスコープが導出されます。「a または b」のルールやロール制限（ROOT/ADMIN）も含まれます。ツールの説明にも同じ内容がそのまま記載されます。
許可される値。 値リストが宣言されたフィールド（ssl_provider、web_server、restart_policy など）には、JSON Schema の enum と default が設定されるため、モデルが推測する必要はありません。
大きなリストも扱いやすい。 リストを返すすべての GET は _limit、_fields、_match を受け付けます。サーバーがレスポンスに適用するため（パネルには渡されません）、{total, matched, shown} が報告され、500 件のドメインがあるパネルも 1 回の呼び出しで検索できます。
検証エラーにはフィールド名が示されます。 Gin の検証失敗は、モデルが使った JSON 名を使って field "user_id" is required / field "type" must be one of the allowed values のように変換されます。
検索ではユーザーの言葉が使えます。 panelica_find_tools は website→domain、certificate→ssl、mailbox→email、container→docker にマッピングし、複数形の語幹も処理するため、最初の検索で適切なツールが見つかります。
一時的な制限は自動で処理されます。 リセットまで 15 秒以内の 429 は 1 回待機し、ネットワークエラーが発生した GET は 1 回再試行されます。パネルとの時刻のずれが 2 分を超えると指示内で警告されます（HMAC タイムスタンプは拒否されます）。
ツールごとの説明には HTTP ルート、必要なスコープ、レスポンスエンベロープと最初のデータフィールドを示す Returns: 行、リスク区分（読み取り専用／変更／破壊的）が含まれます。
ID パラメーターには取得元が示されます — パス、クエリ、本文の各フィールドに対して、UUID of the domain — obtain it from GET /v1/domains のように記載されます。新しいパネルではこれが仕様に含まれています。古いパネルではサーバーが導出します。
panelica_describe_tool は、1 つのツールの正確なパラメーター、本文フィールド、レスポンスフィールドを返すため、モデルは呼び出す前に確認できます。
エラーはそのまま返されず、説明が付けられます：403 では不足しているスコープと再試行しても解決しないことが示され、404 では再度リストを取得して実在する ID を使うよう案内され、429 ではリセットまでの時間が報告されます。5xx ではループせずに報告するよう案内されます。参照用に、パネルからの生のレスポンスも追加されます。
結果のサイズには上限があります：大きすぎるリストレスポンスは最初の項目までに切り詰められ、明示的な _truncated 注記が付きます（有効な JSON のまま）。コンテキストがあふれるのを防ぎます。
リソース（対応クライアント向け）：panelica://guide（指示）、panelica://catalogue（ルートと概要を含むすべてのツール）、およびライブモードでの panelica://spec（パネルの完全な API 仕様）。

レスポンスフィールドの一覧は、パネルの /v1/api-spec から取得されます。新しいパネルでは、ビルド時にハンドラーのソースから生成されます。これより前のパネルでも動作しますが、そのツールにはフィールド名ではなく {status, data} のみが表示されます。

ツールカタログ

488 個のツールがパネルのライブ /v1/api-spec から自動生成されるため、API とのずれが生じません。各ツールには MCP の安全性アノテーション（ 181 · 177 · 46）が付与されており、対応するクライアントは読み取りを自動承認し、破壊的な呼び出しの前に警告できます。本文フィールドとクエリパラメーターは、パネルのハンドラーコード（パネルリポジトリ内の gen-external-schemas）から導出されるため、1.0.528 以降のパネルでは、変更を伴うツールに型付きの必須マーク付き本文が設定され、…/suspend や …/restart などのアクションエンドポイントは本文を一切受け取らないことが明示されます。

カテゴリ	ツール数
Git	43
ドメイン	32
ログ	26
ファイルマネージャー	23
Laravel アプリ	21
Python アプリ	19
Node.js アプリ	18
アカウント	16
CloudFlare	12
Docker	12
IP アドレス	9
cron ジョブ	8
メール	8
FTP	8
セキュリティ	8
データベース	7
スパム	7
SSH ユーザー	7
WordPress	7
API キー	6
ライセンス	6
MySQL ユーザー	6
サーバー	6
Webhook	6
バックアップ	5
DNS	5
移行	5
プラン	5
スナップショット	5
2FA	4
ウイルス対策	4
バックアップスケジュール	4
メーリングリスト	4
SSL	4
帯域幅	3
設定ロック	3
コア	3
リモート MySQL	3
セッション	3
サブドメイン	3
ターミナル	3
監査	2
メトリクス	2
通知	2
パネル設定	2
リソースクォータ	2
SMTP リレー	2
システム cron	2
メールキュー	1
PHP	1
リダイレクト	1

機械可読な一覧はこちらです：tools/tools.json。

セッションの例

サーバーを接続したら、MCP クライアントで次の例を試してください。

ドメインのプロビジョニング。

"starter プランで [email protected] の新しいアカウントを作成し、そのアカウントにドメイン alice-shop.com を追加して、Let's Encrypt 証明書を発行してください。"

アシスタントはカタログから panelica_accounts_post_v1_accounts、panelica_domains_post_v1_domains、panelica_ssl_post_v1_ssl_... を選び、会話の内容からパラメーターを設定して、順番に呼び出します。呼び出しの様子はクライアントのツールログで確認できます。

診断。

"alice-shop.com の過去 24 時間の帯域幅使用量を表示し、今月のプランのクォータを超過する見込みかどうか教えてください。"

一括クリーンアップ。

"SSL 証明書の有効期限が今後 14 日以内に切れるすべてのドメインを一覧表示し、すべて更新してください。"

DNS 移行。

"ゾーン alice-shop.com の現在の A レコードと CNAME レコードを一覧表示し、www を alice-shop.com の CNAME として追加して、203.0.113.10 を指す mail の A レコードを追加してください。"

アシスタントは API キーに許可されたスコープのツールのみを呼び出すため、読み取り専用キーでは「一覧表示」の質問には安全に回答できますが、「作成／削除」は拒否します。

権限スコープ

API キーにはスコープを設定できます。AI アシスタントには、必要なアクセス権だけを付与してください。パネルでキーを作成する際、スコープは事前に選択されていません。また、作成ダイアログでは 50 個すべてのスコープを対象にライブ検索できます。表示／一覧表示のみ · 作成／更新 · 削除 · 特別なアクセス。どのファミリーでもワイルドカード（domains:*）を利用でき、*:* はすべてのアクセスを許可します。

領域	スコープ
アカウント	`accounts:read` · `accounts:write` · `accounts:delete`
ドメインとサブドメイン	`domains:read` · `domains:write` · `domains:delete`
データベース	`databases:read` · `databases:write` · `databases:delete`
DNS	`dns:read` · `dns:write` · `dns:delete`
メール	`email:read` · `email:write` · `email:delete`
FTP	`ftp:read` · `ftp:write` · `ftp:delete`
SSL	`ssl:read` · `ssl:write`
バックアップとスナップショット	`backups:read` · `backups:write` · `backups:restore`
ファイルマネージャー	`files:read` · `files:write` · `files:delete`
CloudFlare	`cloudflare:read` · `cloudflare:write` · `cloudflare:delete`
Dockerとアプリテンプレート	`docker:read` · `docker:write` · `docker:delete`
アプリホスティング（Laravel / Node.js / Python）	`apps:read` · `apps:write` · `apps:delete`
Gitとデプロイ	`git:read` · `git:write` · `git:delete`
ログと監査	`logs:read` · `logs:write`
セキュリティ（ウイルス対策、ファイアウォール、IPブロック）	`security:read` · `security:write` · `security:delete`
サーバーとインフラストラクチャ	`server:read` · `server:write`
サービス制御	`services:restart` · `services:start` · `services:stop`
プラン	`plans:read` · `plans:write`
Webhook	`webhooks:read` · `webhooks:write` · `webhooks:delete`
帯域幅	`bandwidth:read`
ライセンス	`license:read`
移行（パネル間）	`migrations:read`
ターミナル	`terminal:access`
フルアクセス	`:`
変更を伴うサービス制御には、意図的に専用のアクションスコープ（または
`server:write`）が必要です。メトリクス専用の `server:read` キーでは、MySQL を停止できません。

レート制限

API キーにはレート制限ティアが設定されています（キー作成時の rate_limit_tier： starter は 60/分、professional は 300/分、business は 1000/分、enterprise は無制限）。デフォルトの starter ティアは、アシスタントが多数の呼び出しを並行して行うと簡単に上限に達します。429 RATE_LIMIT_EXCEEDED が表示される場合は、アシスタント用のキーをより高いティアで作成してください（レスポンスに reset_at が含まれます）。

セキュリティモデル

HMAC-SHA256 リクエスト署名。 すべてのリクエストは、API シークレットを使って METHOD + PATH + QUERY + TIMESTAMP + BODY に対して署名されます。パネルはサーバークロックとの時刻のずれが 5 分を超えるリクエストを拒否するため、リプレイ攻撃は不可能です。
シークレットはローカルに保持されます。 API シークレットはプロセス環境から読み込まれ、署名の計算にのみ使用されます。ログに記録されたり、サードパーティーに送信されたり、ディスクに書き込まれたりすることはありません。
スコープ制限付きキー。 ユースケースごとに API キーを 1 つ生成してください。そのユースケースに必要なスコープのみを付与します。たとえば、読み取り専用アシスタントには domains:read、完全自動化には *:write のみを付与します。
監査証跡。 すべてのリクエストは、パネルの通常の監査ログと RBAC を通過します。MCP 経由で実行されたアクションは、ほかの認証済み API 呼び出しと区別できず、それを実行した API キーまで追跡できます。
データ収集なし。 このサーバーはテレメトリを送信せず、キャッシュを書き込まず、サードパーティーに接続しません。
コンテナーの強化。 Docker イメージは非 root ユーザーとして実行され、ポートを公開しません。 stdio のみで通信します。

トラブルシューティング

症状	考えられる原因	対処方法
クライアントに「利用可能なツールが 0 個」と表示される	起動時にサーバーがクラッシュしました。通常は環境変数が不足しています	3 つの環境変数を設定したシェルから `panelica-mcp` を一度実行し、stderr を確認してください
`401 MISSING_API_KEY`	`PANELICA_API_KEY` が設定されていないか、ヘッダーの引き継ぎが正しくありません	MCP クライアントの設定を再確認し、編集後にクライアントを再起動してください
`401 INVALID_SIGNATURE`	`PANELICA_API_SECRET` が間違っているか、時刻のずれが 5 分を超えています	MCP ホストとパネルホストの両方で `chronyc tracking`（または `timedatectl status`）を実行してください
`401 INVALID_TIMESTAMP`	ローカルクロックのずれが 5 分を超えています	MCP ホストで NTP を同期してください
`BASE_URL` への接続がタイムアウトする	ホストまたはポートが間違っています。通常は URL の末尾に `:8443/api/external` がありません	`curl -sk $PANELICA_BASE_URL/health` で確認してください。`{"status":"ok"}` が返るはずです
ツールの結果が `Panelica API error 403` で始まり、スコープ名が示される	API キーにそのスコープがありません	パネルのキーにスコープを追加してください（Settings → API Keys）。アシスタントには再試行しないよう指示されています
ツールの結果に `Panelica API error 404 … re-list` と表示される	アシスタントが、このキーの所有者に存在しない ID を使用しました	サーバー側で修正することはありません。この案内により、アシスタントは再度一覧を取得し、実在する ID を選びます
ツールの説明に「スキーマが静的に宣言されていません」と表示される	エンドポイントが動的なリクエストボディ（map / multipart）を受け取ります	自由形式の `body` オブジェクトを渡してください。パネルは検証し、不足しているフィールドを含む 400 を返します。アシスタントにはその内容を確認するよう指示されています
起動ログに `clock skew of Ns versus the panel` と表示される	MCP ホストのクロックがずれています	MCP ホストで NTP を同期してください。署名付きリクエストには、パネルが確認するタイムスタンプが含まれます
起動ログに `startup credential check failed` と表示される	`GET /v1/me` でキーまたはシークレットが拒否されました	手順はすでにアシスタントに伝えられています。パネルでキーを修正し、クライアントを再起動してください
TLS の検証に失敗する	パネルで自己署名証明書が使用されています	MCP ホストがその CA を信頼していれば、そのまま動作します。信頼していない場合は、パネルに正式な証明書を導入してください（パネル UI → Settings → SSL）。クライアント側で TLS 検証を無効にしないでください

それでも解決しない場合は、（機密情報を伏せた）stderr の出力を添えて github.com/Panelica/panelica-mcp/issues で issue を作成してください。

開発

git clone https://github.com/Panelica/panelica-mcp.git
cd panelica-mcp
npm install
npm run build
node dist/index.js

プロジェクト構成：

.
├── src/index.ts          # MCP server (stdio transport, HMAC client, live-spec loader)
├── src/catalog.ts        # spec → tools generator (shared by runtime and build script)
├── src/toolsets.ts       # core set, PANELICA_TOOLSETS selection, find/describe/call meta tools
├── src/instructions.ts   # server instructions generated from the catalogue
├── src/errors.ts         # error explanations + result bounding
├── tools/
│   ├── build-tools.mjs   # Generates tools.json from the API spec
│   ├── api-spec.json     # Committed snapshot of the live /v1/api-spec
│   └── tools.json        # tool definitions, auto-generated (committed)
├── .github/workflows/
│   └── refresh-tools.yml # Weekly CI: regenerate, bump, tag, publish npm + Docker + Registry
├── Dockerfile
├── smithery.yaml         # Smithery deployment manifest
├── .env.example
└── README.md

ツールカタログを最新の状態に保つ

カタログが手作業で API とずれることはありません。バックエンドは常に最新の /v1/api-spec（ルートレジストリから生成）を提供し、ツールはそこから再生成されます。

# Rebuild from the committed snapshot (offline):
npm run rebuild-tools

# Pull the live spec, refresh the snapshot, and rebuild:
PANELICA_SPEC_URL="https://your-panel:8443/api/external/v1/api-spec" npm run rebuild-tools

CI（refresh-tools.yml）は、PANELICA_SPEC_URL リポジトリ シークレットに指定されたパネルを対象に、毎週この処理を実行します。カタログに変更があった場合、同じ実行内でパッチバージョンを更新し、タグを付け、npm、Docker イメージ、MCP Registry のエントリーを公開します。そのため、新しい API エンドポイントは npx -y panelica-mcp のユーザーに自動的に届きます。稼働中のサーバーでは、その必要すらありません。デフォルトのライブカタログを使う場合、接続先のパネルから仕様を読み取ります。各ツールには安全性アノテーション（GET の readOnlyHint、DELETE の destructiveHint）が付与されており、対応する MCP クライアントはこれを使って読み取りを自動承認し、破壊的な呼び出しの前に警告できます。

トレーニング目的で、すべてのパネルエンドポイント（合計 1,263 件）を含む別の内部データセットがあります。このパッケージで公開されるのは、ドキュメント化された External API エンドポイント 404 件のみです。内部パネルエンドポイント、記録された DEV データ、トレーニング用 jsonl ファイルは、公開リポジトリには含まれません。

バージョン管理とサポート

このパッケージは Panelica パネルの External API に準拠しています。ツールのシグネチャが変更されるのは、パネル自体で後方互換性のない API 変更がリリースされた場合のみで、その際はパッケージのメジャーバージョンも合わせて更新されます。
新しいエンドポイントは、次回 tools/tools.json を再生成してリリースを公開したときに利用可能になります。またはライブモードでは、独自のパネルの /v1/api-spec からすぐに利用できます。
レスポンスフィールドの一覧、ID の由来、整備済みの説明はパネルの仕様から取得します。それらに対応する前のバージョンのパネルでも、より簡素なツールで引き続き動作します。
パネルに関する問題（このクライアントではなく、API 自体の問題）：Panelica フォーラム（forum.panelica.com）。
クライアント／パッケージングに関する問題： github.com/Panelica/panelica-mcp/issues。

ライセンス

MIT。LICENSEを参照してください。

リンク

Panelica のウェブサイト：https://panelica.com
ライブデモ：https://demo.panelica.com
ドキュメント：https://panelica.com/docs
フォーラムとサポート：https://forum.panelica.com
公開インストーラー：https://latest.panelica.com/install.sh

Markdown 対応

ログインしてコメント

基本情報

作者: Panelica
言語: node
バージョン: 0.5.2
トランスポート: stdio
掲載日: 2026年10月12日
最終更新: 3 日前
公式 Registry: io.github.Panelica/panelica-mcp

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。