tronbyt-mcp

tronbyt-mcp

AI アシスタントから LED サインに表示を送れるようにします。

セルフホストの tronbyt/server で管理されている Tidbyt または Tidbyt 形式の LED マトリクスディスプレイをお持ちの場合、これを Claude（またはアシスタントがツールを使えるようにするオープン標準の MCP に対応したほかの AI ツール）に接続できます。インストールすると、ディスプレイについてアシスタントに話しかけるだけで操作できるようになります。

「サインにアンバー色で BREAD'S DONE と表示して。」 「ディスプレイを 20% に暗くして、午後 10 時から午前 7 時までナイトモードをオンにして。」 「今サインに表示されているアプリは何？ 株価ティッカーを無効にして。」 「時計アプリをしばらく表示して。」

あとはアシスタントが処理します。テキストをディスプレイのピクセル形式にレンダリングし、サーバーと通信して、アプリのローテーションを管理します。すべてがご自身のマシン上でご自身のサーバーに対して実行され、クラウドサービスを経由することはありません。

仕組み

tronbyt-mcp は、tronbyt/server の公開されている REST API をラップする小規模な MCP サーバーです。MCP クライアント（Claude Code、Claude Desktop など）がこれをローカルで起動し、stdio 経由で通信します。MCP サーバーはデバイス API キーを使って、HTTP 経由で Tronbyt サーバーと通信します。

要件

• セルフホストの tronbyt/server（v2.x）で管理されているディスプレイ。サーバーが管理するデバイスであれば何でも動作します。もともと Tidbyt として販売されたデバイスである必要はありません。Tidbyt Gen1/Gen2、Tronbyt S3 および S3 Wide キット、MatrixPortal S3（Waveshare 版を含む）、Waveshare S3、Pixoticker、Raspberry Pi ディスプレイ、そしてタイプが「other」の自作パネルに対応しています。標準の 64×32 パネルとワイド 128×64（2x）パネルの両方をサポートしています。
• Node.js ≥ 20.9
• MCP クライアント：Claude Code、Claude Desktop、または MCP stdio サーバーに対応したほかのクライアント。

インストール

1. デバイス API キーを取得する

Tronbyt のウェブ UI でデバイスの設定を開き、API キーをコピー（または生成）します。キーは個々のデバイスに紐づいています。1 つのキーにつき 1 台のディスプレイです。

2. MCP クライアントにサーバーを追加する

Claude Code（コマンド 1 つ）：

claude mcp add tronbyt \
  -e TRONBYT_BASE_URL=http://tronbyt.local:8000 \
  -e TRONBYT_API_KEY=<your-device-key> \
  -- npx -y tronbyt-mcp

Claude Desktop：設定ファイルを編集します — macOS：~/Library/Application Support/Claude/claude_desktop_config.json、 Windows：%APPDATA%\Claude\claude_desktop_config.json — 次を追加します：

{
  "mcpServers": {
    "tronbyt": {
      "command": "npx",
      "args": ["-y", "tronbyt-mcp"],
      "env": {
        "TRONBYT_BASE_URL": "http://tronbyt.local:8000",
        "TRONBYT_API_KEY": "<your-device-key>"
      }
    }
  }
}

その後、Claude Desktop を再起動します。

ほかの MCP クライアント：コマンドに npx、引数に ["-y", "tronbyt-mcp"]、そして上記 2 つの環境変数を指定して、stdio サーバーを設定します。

ソースからインストール（npx の代わり）：

git clone https://github.com/jonfishr/tronbyt-mcp.git
cd tronbyt-mcp
npm install && npm run build

その後、MCP クライアントの設定でサーバーコマンドとして node /path/to/tronbyt-mcp/dist/index.js を使用します（環境変数は同じです）。

複数のディスプレイを使う場合：API キーはデバイスごとに異なるため、ディスプレイごとにそれぞれ独自のキーを指定したエントリを追加します（tronbyt-kitchen、tronbyt-office など）。

3. 動作を確認する

「Tronbyt デバイスの一覧を表示して」 のようにアシスタントに尋ねてください。明るさ、ナイトモード、アプリ一覧とともにディスプレイが表示されます。（Claude Code では /mcp でもサーバーとそのツールを確認できます。）

設定

環境変数	必須	デフォルト	備考
TRONBYT_BASE_URL	はい	—	tronbyt/server の URL。例：http://tronbyt.local:8000
TRONBYT_API_KEY	はい	—	Tronbyt のウェブ UI で取得するデバイスごとの API キー
TRONBYT_TIMEOUT_MS	いいえ	10000	リクエストごとのタイムアウト

使用方法

これらのツールを直接呼び出す必要はありません。リクエストに応じてアシスタントが適切なツールを選びます。 利用できるツールは次のとおりです。

ツール	機能
list_devices	キーから確認できるデバイスの情報を取得します。明るさ、ナイトモード、固定アプリ、最終確認時刻が含まれます
update_device	明るさ、回転間隔、ナイトモード／減光モード、固定アプリを設定します
reboot_device	ディスプレイを再起動します
list_installations	デバイスにインストールされているアプリを、状態と設定とともに取得します
update_installation	インストールを有効化／無効化、固定／固定解除、または表示時間変更します
delete_installation	インストールと、そのレンダリング済み画像を削除します
push_app	サーバー側のアプリをレンダリングし（設定は任意）、表示します
push_image	base64 WebP（64×32、ワイドディスプレイの場合は128×64）をディスプレイに直接送信します
push_text	ディスプレイサイズのWebPにテキストをローカルでレンダリングし、送信します

プッシュツールには background を指定します。false（デフォルト）の場合、ディスプレイを中断してすぐに表示します。true の場合、中断せずにローテーションに保存します。キーから認識できるデバイスが1台だけの場合（通常はこちら）、device_id の指定は不要です。

push_text

テキストはTom Thumbの3×5ピクセルフォントでレンダリングされ、単語単位で折り返されて中央揃えになります。印字可能なASCII文字のみ対応しています。\n を指定すると改行します。色は16進数（#ffcc00）で指定し、デフォルトは黒地に白です。

キャンバスサイズはデバイスタイプから自動検出されます（size: "auto"）。標準ディスプレイは64×32、ワイド／2xディスプレイ（tronbyt_s3_wide、raspberrypi_wide）は128×64です。ワイドディスプレイでは、デフォルトでフォントが2倍になります。文字数と行数は同じ16文字×5行で、ピクセル数が2倍になります。ネイティブサイズのグリフを使う場合は text_size: "small"（32文字×10行）を指定するか、size: "64x32"／"128x64" を指定して自動検出を上書きします。

削除

• Claude Code： claude mcp remove tronbyt
• Claude Desktop／その他のクライアント： 設定ファイルから "tronbyt" エントリを削除し、クライアントを再起動します。
• ソースからインストールした場合： クローンしたディレクトリを削除します。npx を使った場合は、キャッシュされたコピーが ~/.npm/_npx に残ることがあります。サイズは小さく無害なので、そのままにするか、npm cache clean --force で削除してください。
• サーバー上： 送信したものはすべてデバイスのインストールとして表示されます。アシスタントに削除を依頼するか、TronbytのWeb UIで削除してください。使用を終える場合は、Web UIでAPIキーを無効化してください。それ以外の情報はどこにも保存されません。

開発

npm install
npm test            # vitest: unit + in-process MCP + stdio e2e (builds first)
npm run build       # tsc -> dist/
npm run gen:font    # regenerate src/font.ts from scripts/tom-thumb.bdf

実際のサーバーに対するスモークテストです（破壊的な操作は行いません。バックグラウンドモードでローテーションに送信した後、インストールを削除します）。ビルド後にリポジトリのルートから実行してください。

TRONBYT_BASE_URL=http://tronbyt.local:8000 TRONBYT_API_KEY=<key> scripts/smoke.sh

対象外（v1）

• update_firmware_settings — 意図的に対象外としています。不適切な値を設定すると、ディスプレイに接続できなくなる場合があります
• アニメーション（複数フレームのWebP）、URLによる画像指定
• HTTPトランスポート（stdioのみ）

ライセンス

MIT。バンドルされているピクセルフォントは、Brian J. SwetlandとRobey PointerによるTom Thumb／「Fixed4x6」（MIT）で、scripts/tom-thumb.bdf として同梱されています。このプロジェクトは、Tidbyt（企業）またはTronbytプロジェクトとは無関係です。