ThingsPanel MCP

ThingsPanel MCP

ThingsPanel MCP は、MCP 互換のアシスタントを ThingsPanel および ThingsVis API に接続します。特化型の IoT ツールと、固定されたソース監査済みルートを持つ個別名称の API ツールを提供します。

English | 中文

含まれる機能

• 378 個の MCP ツール：生成された API ツール 364 個と、デバイス、テレメトリ、ダッシュボード、制御に特化したツール 14 個。
• 生成されたツール一式は、デバイス、テレメトリ、アラーム、グループ、製品、サービスアクセス、ダッシュボード、アップロードなどを含む、ThingsPanel API 操作 312 個と ThingsVis API 操作 52 個をカバーします。
• 生成された読み取り操作は 178 個です。残りの書き込みまたは制御操作には、ツール引数 confirmed=true が必要です。
• 構造化 JSON 結果、ビジネスコードエラーの検出、パスのエンコード、ファイルのアップロードサポート、範囲を制限した SSE/WebSocket 読み取り。
• ThingsPanel および ThingsVis の認証プロファイル。認可は常に接続先サービスによって適用されます。

許可リストに登録された API の完全な一覧は src/thingspanel_mcp/api_manifest.json にあります。ツール定義によって HTTP メソッドとルートが固定されており、呼び出し元は path_params、query、body、および任意の file_path の値を指定します。

特化型の 14 個のツールは、ok、summary、data、error フィールドを含む型付き MCP structuredContent を返します。プログラムによる判断には data フィールドを使用してください。summary は人向けです。send_device_command は利用可能な場合に message_id を返します。コマンドの受領確認を問い合わせるには、その値を get_device_command_status に渡してください。コマンドが受け付けられたとしても、デバイスが実行した証拠にはなりません。

要件とインストール

• Python 3.8 以降。
• ThingsPanel アカウントと、対象 API で受け入れられる認証情報。ThingsVis の操作には ThingsVis の認証情報も必要な場合があります。

PyPI からインストールします：

python -m pip install --upgrade thingspanel-mcp

永続的なインストールをせずに uv で実行します：

uvx --from thingspanel-mcp thingspanel-mcp --help

ソースからインストールします：

git clone https://github.com/ThingsPanel/thingspanel-mcp.git
cd thingspanel-mcp
python -m pip install .

認証と権限

ThingsPanel Community は SYS_ADMIN と TENANT_ADMIN をサポートしています。テナントのサブユーザーはなく、テナントユーザーアカウントは Enterprise エディションの機能です。ThingsPanel の API キーには、テナント管理者の権限が割り当てられます。システム管理者は ThingsPanel のログイン JWT を使用する必要があります。

ThingsVis の認証情報は ThingsPanel の認証情報とは別です。ThingsVis の SSO 連携では、選択したプロファイルの ThingsPanel JWT を使用します。ThingsVis はサーバー間でそのトークンを検証し、確認済みの ID からロールを判定します。MCP 呼び出し元がロールやユーザー ID を指定して、権限を昇格させることはできません。

ID ごとにプロファイルを作成してください。ツールでプロファイルを指定しない場合は、デフォルトのプロファイルが使用されます。14 個の用途別の便利なツールではデフォルトのプロファイルが使用され、生成された API ツールでは明示的にプロファイルを指定できます。

~/.thingspanel/config.json を作成します。

{
  "base_url": "https://thingspanel.example.com",
  "api_prefix": "/api/v1",
  "thingsvis_base_url": "https://thingsvis.example.com",
  "thingsvis_api_prefix": "/api/v1",
  "profiles": {
    "default": {
      "thingspanel_token": "<tenant-admin-jwt>",
      "thingsvis_token": "<thingsvis-jwt>",
      "thingsvis_open_api_key": "<dashboard-open-api-key>"
    },
    "tenant_admin": {
      "thingspanel_token": "<tenant-admin-jwt>"
    },
    "superadmin": {
      "thingspanel_token": "<sys-admin-jwt>"
    }
  }
}

このファイルは非公開にしてください。macOS または Linux では、chmod 600 ~/.thingspanel/config.json を実行してアクセスを制限します。実際の認証情報をコミットしないでください。

環境変数を使用して、デフォルトのプロファイルとエンドポイントを上書きできます。

THINGSPANEL_CONFIG_PATH
THINGSPANEL_BASE_URL
THINGSPANEL_API_PREFIX
THINGSPANEL_TOKEN
THINGSPANEL_API_KEY
THINGSPANEL_REFRESH_TOKEN
THINGSVIS_BASE_URL
THINGSVIS_API_PREFIX
THINGSVIS_TOKEN
THINGSVIS_REFRESH_TOKEN
THINGSVIS_OPEN_API_KEY
THINGSVIS_INTERNAL_SECRET

名前付きプロファイルの認証情報には、THINGSPANEL_PROFILE_TOKEN、THINGSPANEL_PROFILEAPI_KEY、THINGSPANEL_PROFILETHINGSPANEL_REFRESH_TOKEN、THINGSPANEL_PROFILETHINGSVIS_TOKEN、THINGSPANEL_PROFILE_THINGSVIS_REFRESH_TOKEN を使用します。たとえば、THINGSPANEL_PROFILE_SUPERADMIN_TOKEN です。環境変数の認証情報は、プロセスの起動時に読み込まれます。

デフォルトの ID を 1 つだけ使用する場合は、コマンドラインも利用できます。

thingspanel-mcp --token "<ThingsPanel login JWT>" --base-url "https://thingspanel.example.com"

テナント管理者として接続する場合に限り、--api-key を使用してください。トークンと API キーを指定するコマンドライン引数は、ローカルのプロセス検査で表示される場合があります。保護された設定ファイルまたはシークレットマネージャーを使用することをおすすめします。

MCP クライアントを設定する

デフォルトのトランスポートは stdio です。SSE は --transport sse で利用できます。保護された設定ファイルをサーバーに指定するか、クライアントの環境変数サポートを使用して、認証情報をクライアントの設定の外部に保管してください。

Codex

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

[mcp_servers.thingspanel]
command = "uvx"
args = ["--from", "thingspanel-mcp==0.1.11", "thingspanel-mcp"]

[mcp_servers.thingspanel.env]
THINGSPANEL_CONFIG_PATH = "/absolute/path/to/.thingspanel/config.json"

設定を変更した後、Codex の MCP サーバーを再起動するか、更新してください。

Claude Desktop

claude_desktop_config.json にサーバーエントリを追加します。

{
  "mcpServers": {
    "thingspanel": {
      "command": "uvx",
      "args": ["--from", "thingspanel-mcp==0.1.11", "thingspanel-mcp"],
      "env": {
        "THINGSPANEL_CONFIG_PATH": "/absolute/path/to/.thingspanel/config.json"
      }
    }
  }
}

WorkBuddy

ローカルの stdio で使用するには、~/.workbuddy/mcp.json にサーバーエントリを追加します。

{
  "mcpServers": {
    "thingspanel": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "thingspanel-mcp==0.1.11", "thingspanel-mcp"],
      "env": {
        "THINGSPANEL_CONFIG_PATH": "/absolute/path/to/.thingspanel/config.json"
      }
    }
  }
}

このローカル設定は、WorkBuddy マーケットプレイスのコネクター公開とは別のものです。マーケットプレイスへの申請には、コネクターのメタデータ、MCP マニフェスト、アイコン、審査も必要です。ユーザーが入力する認証情報については、WorkBuddy のトークン認証設定に従ってください。標準的な MCP ツールスキーマでは Skill は任意ですが、この多数のツールの中から適切なものを選び、安全なワークフローを進めるためのガイドとして役立ちます。WorkBuddy コネクターガイドを参照してください。

ツールの呼び出し

生成された各ツールは、許可リストに登録された API 操作を 1 つだけ実行します。たとえば、デバイス詳細ツールでは、ルート識別子に path_params を使用します。

path_params = {"id": "device-id"}
profile = "tenant_admin"

クエリパラメーターは query に、JSON リクエストデータは body に指定します。ファイルアップロードツールでは file_path を指定し、必要に応じて upload_field も指定します。要求されたデータを管理する profile を選択してください。MCP サーバーに別のロールを装うよう求めないでください。

生成された書き込みツールまたは制御ツールを呼び出す前に、まず実行する操作を説明し、ホストアプリケーションでユーザーの承認を得てください。その後、confirmed=true を指定してツールを呼び出します。confirmed が false の場合、ツールはリクエストを送信せず、confirmation_required とリクエストのプレビューを返します。このフラグは追加の保護策であり、ユーザーの承認やバックエンドの認可に代わるものではありません。

ストリーミングツールでは、stream_messages に 1～20、stream_seconds に 1～30 を指定できます。デフォルトはそれぞれ 5 メッセージ、5 秒です。

結果とトラブルシューティング

成功時の呼び出しでは、次のような構造化された結果が返されます。

{"ok": true, "status": 200, "data": {...}}

失敗時は、利用可能な場合、status とエラー情報を含む ok=false が返されます。HTTP ステータスが 200 の場合でも、ThingsPanel のビジネスコードは確認されます。

• プロファイル名を示す設定エラーは、そのプロファイルがないか、そのサービスの認証情報が不足していることを意味します。
• 401 または 403 は、認証情報が無効であるか、サービス側のロールにその操作へのアクセス権がないことを意味します。
• confirmation_required を含む応答は、書き込み操作のプレビューです。操作の承認後に限り、confirmed=true を設定してください。
• missing_path_parameter エラーは、必須のルート値が path_params にないことを意味します。
• SSE と WebSocket の結果には意図的に上限が設定されています。不完全な結果は、設定された時間またはメッセージ数の上限に達した可能性があります。
• URL またはプロキシに関する問題がある場合は、その環境のサービスのベース URL と API プレフィックスを確認してください。

セキュリティに関する注意

• サーバーは呼び出し元が指定したロールを信頼しません。接続先のバックエンドが権限の基準となります。
• API ツールは、リポジトリにチェックインされたマニフェストに基づいて許可リストに登録されています。任意のメソッドや URL は受け付けません。
• 生成された 186 個の書き込み・制御ツールでは confirmed=true が必要であり、バックエンドの権限設定も引き続き適用されます。
• リクエストエラーの処理時にトークンや API キーが出力されることはありません。ローカル設定ファイルは非公開にし、組織のポリシーに従って認証情報を定期的に更新してください。

開発

python -m pytest で単体テストを実行します。python -m build でリリースファイルをビルドし、続けて python -m twine check dist/* でメタデータを検証します。tools/build_api_manifest.py でチェックイン済みの API 一覧を再生成し、tools/audit_apifox_source.py でソースドキュメントとの差異を確認できます。

ライセンス

Apache License 2.0 です。LICENSE を参照してください。