thingsboard-mcp-server

ThingsBoard MCP サーバー

ThingsBoard 向けの Model Context Protocol（MCP） サーバーです。このプロジェクトを使うと、AI アシスタント（Claude Desktop など）が ThingsBoard インスタンスと直接やり取りし、アセット、デバイス、テレメトリー、アラームなどを管理できます。

ツールは公式 Python SDK（tb-rest-client）から自動生成されるため、API を 100％網羅し、厳密な型チェックを行い、ソースコードから直接取得した詳細なドキュメントを提供します。

🚀 特長

• 自動検出： インストール済みの ThingsBoard SDK のエディション（CE または PE）を自動検出し、それに応じて適応します。
• スマートトレース： 高レベルのクライアントメソッド（rest_client_ce.py）を基盤となる API コントローラーに対応付け、正確な docstring とシグネチャを抽出します。
• 厳密な検証： SDK をモックし、生成されたすべてのツールに有効な入力、docstring、実行ロジックがあることを確認するテストスイート（verify_tools.py）を備えています。
• 包括的なレポート： 詳細な Markdown ドキュメント（TOOLS_CE.md）と検証監査レポート（VERIFICATION_REPORT_CE.md）を生成します。

---

📋 前提条件

• Python 3.10 以降
• ThingsBoard Python REST Client

pip install tb-rest-client

🛠️ セットアップと生成

1. ツールを生成する ジェネレータースクリプトを実行します。インストール済みの tb-rest-client ライブラリをスキャンし、メソッド呼び出しをトレースして、MCP ツールのコードを生成します。

python3 generate_thingsboard_mcp.py

実行内容

• thingsboard_mcp/tools/ce/（インストールされている場合は pe/ も）を作成します。
• 利用可能なすべてのツール、その説明、パラメーターを一覧にした TOOLS_CE.md ファイルを生成します。
• 内部ユーティリティメソッドとラムダを自動的に除外します。

2. ツールを検証する 検証スイートを実行して、生成されたコードが有効であり、厳格な品質基準に準拠していることを確認します。

python3 verify_final.py

実行内容

• ThingsBoard SDK をモックします（実際の接続は不要です）。
• ダミーデータを使ってすべてのツールをテストし、クライアントが正しく呼び出されることを確認します。
• 各ツールの合格／不合格ステータスを記載した VERIFICATION_REPORT_CE.md を生成します。

⚙️ 設定

ThingsBoard インスタンスに接続するには、次の環境変数が必要です。

変数	説明	デフォルト
TB_URL	ThingsBoard の URL	http://localhost:8080
TB_USERNAME	テナント管理者のユーザー名	[email protected]
TB_PASSWORD	テナント管理者のパスワード	tenant
TB_EDITION	読み込むエディション（CE または PE）	PE

🏃‍♂️ 使用方法

オプション A：Claude Desktop で使用する

次の設定を Claude Desktop の設定ファイルに追加します。 MacOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "thingsboard": {
      "command": "python3",
      "args": ["/absolute/path/to/thingsboard-mcp/thingsboard_mcp/main.py"],
      "env": {
        "TB_URL": "http://YOUR_TB_IP:8080",
        "TB_USERNAME": "[email protected]",
        "TB_PASSWORD": "your_password",
        "TB_EDITION": "CE"
      }
    }
  }
}

オプション B：手動で実行する（テスト）

接続のテストやデバッグを行うには、ターミナルでサーバーを直接実行できます。

export TB_URL="http://localhost:8080"
export TB_USERNAME="[email protected]"
export TB_PASSWORD="tenant"
export TB_EDITION="CE"

python3 thingsboard_mcp/main.py

📂 プロジェクト構成。

├── generate_thingsboard_mcp.py # Scans SDK and generates tool code
├── verify_tools.py             # Mocks SDK and verifies generated tools
├── TOOLS_CE.md                 # Documentation of all generated tools
├── VERIFICATION_REPORT_CE.md   # Audit log of tool health
├── README.md                   # This file
└── thingsboard_mcp/            # The generated package
    ├── main.py                 # Entry point for MCP Server
    └── tools/
        ├── shared.py           # Shared utilities (Auth, JSON parsing)
        ├── ce/                 # Community Edition tools (Asset, Device, etc.)
        └── pe/                 # Professional Edition tools (if applicable)

🛡️ トラブルシューティング

ツールが見つからない場合： TOOLS_CE.md または generate_thingsboard_mcp.py のコンソール出力を確認してください。次の場合、ツールはスキップされます。

1. 内部のスレッド処理メソッド（join、start）に該当する。
2. ソース SDK にそのメソッドの docstring がない。
3. メソッドがラムダまたは部分関数である。 接続エラーの場合： サーバーは最初のツール呼び出し時にログインを試みます。MCP サーバーを実行しているマシンから TB_URL にアクセスできることと、認証情報が正しいことを確認してください。