RokuMCP

roku-mcp

Roku デバイスの自動化に対応するModel Context Protocol（MCP）サーバーです。アプリのデプロイ、ECP リモートコントロール、スクリーンショットの撮影、SceneGraph ノードの検査、BrightScript デバッグコンソールへのアクセス用ツールを提供します。

インストール

サーバーは単一の npx コマンドとして提供されています。必要であれば一度だけグローバルにインストールするか、MCP クライアントから npx -y roku-mcp を使って必要に応じて起動できます。どちらも動作します。

npm install -g roku-mcp     # optional, global install
# or just point your client at: npx -y roku-mcp

プラグインモード（Claude Code と Cursor）

非公式のコミュニティツールです。Roku, Inc. とは提携しておらず、同社の推奨を受けたものでもありません。

このリポジトリには、MCP サーバー、ワークフロースキル（skills/）、Cursor ルールをまとめて登録するプラグインも含まれています。

• Claude Code： /plugin marketplace add jack1590/RokuMCP の後に /plugin install roku-mcp@roku-mcp-marketplace を実行します。マニフェスト：.claude-plugin/、.mcp.json。
• Cursor： マニフェストは .cursor-plugin/ と mcp.json にあります。スキルは skills/、ルールは rules/cursor/ にあります。

プラグインを有効にすると、Claude Code はデバイスのホストと開発者パスワードを尋ねます（パスワードは機密情報として保存されます）。両方のクライアントでエントリポイント bootstrap.mjs を使用します。どちらも初回起動時に npm ci と npm run build を実行します（Node 18 以上）。プラグインモード以外では、ROKU_DEVICE_HOST / ROKU_DEVICE_PASSWORD またはプロジェクトの .env も引き続き使用できます。

以下で AI クライアントを設定してください。すべてのプラットフォームで同じ起動コマンドを使用し、異なるのは設定ファイルと再読み込みの手順だけです。

{
  "mcpServers": {
    "roku": {
      "command": "npx",
      "args": ["-y", "roku-mcp"],
      "env": {
        "ROKU_DEVICE_HOST": "192.168.1.XXX",
        "ROKU_DEVICE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "servers": {
    "roku": {
      "command": "npx",
      "args": ["-y", "roku-mcp"],
      "env": {
        "ROKU_DEVICE_HOST": "192.168.1.XXX",
        "ROKU_DEVICE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "roku": {
      "command": "npx",
      "args": ["-y", "roku-mcp"],
      "env": {
        "ROKU_DEVICE_HOST": "192.168.1.XXX",
        "ROKU_DEVICE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "roku": {
      "command": "npx",
      "args": ["-y", "roku-mcp"],
      "env": {
        "ROKU_DEVICE_HOST": "192.168.1.XXX",
        "ROKU_DEVICE_PASSWORD": "your-password"
      }
    }
  }
}

command: npx
args:    ["-y", "roku-mcp"]
env:     { ROKU_DEVICE_HOST: "...", ROKU_DEVICE_PASSWORD: "..." }

エージェントのルール

エージェントの動作を改善するため（observe → act → wait → verify のループ、roku_edit_node が気付かないうちに動作しなくなる RTA の uiElementId に関する注意点、各ツールの使い分け）、このリポジトリには主要なエージェントごとに、そのまま導入できる形式のルールが用意されています。本文は同一で、各エージェントが自動読み込みする形式に合わせてラッパーだけが異なります。

各エージェント用の1行コピーコマンドについては、rules/README.md を参照してください。

クイックスタート

クライアントの接続が完了すると、次の3つのプロンプトをすぐに使って、主な機能グループを試せます。

1. デバイスに接続できることを確認する

Use roku-mcp to query my Roku device info and tell me the model, firmware, and IP.

エージェントは roku_query_device_info（ホストが設定されていない場合は roku_discover も）を呼び出し、1ターンで応答するはずです。

2. スクリーンショットを使って UI を操作する

Press Home, wait 2 seconds, take a screenshot, then move Right twice and
screenshot again. Describe what changed between the two screenshots.

これにより roku_keypress、roku_sleep、roku_screenshot を使った、標準的な observe → act → wait → verify ループを試せます。

3. 実行中のチャンネルをライブ編集する（RTA が必要です。ランタイム UI 編集を参照してください）

On the currently running dev channel, find the label that shows the page
title, change its text to "Hello from MCP", verify the change with
roku_get_value, then change it back.

エージェントは roku_query_app_ui でノードを特定し、uiElementId を取得して、roku_edit_node と roku_get_value を呼び出してから変更を元に戻します。これにより、RTA の接続がエンドツーエンドで機能することを確認できます。

環境変数

どちらも各ツール呼び出しのパラメーターとして渡すことができ、その場合は環境変数の設定が上書きされます。

自動検出

ROKU_DEVICE_HOST が設定されておらず、host パラメーターも指定されていない場合、サーバーは SSDP を使ってローカルネットワーク上の Roku デバイスを自動検出し、最初に見つかったデバイスを使用します。roku_discover ツールを使って、利用可能なデバイスをすべて一覧表示することもできます。パスワードは検出できないため、別途設定する必要があります。

.env ファイルのサポート

サーバーは dotenv を使用して、現在の作業ディレクトリにある .env ファイルを自動的に読み込みます。プロジェクトの .env ですでに ROKU_DEVICE_HOST と ROKU_DEVICE_PASSWORD を使用している場合、追加の設定なしでサーバーがそれらを読み込みます。MCP 設定から env ブロックを省略するだけです。

ROKU_DEVICE_HOST=192.168.1.100
ROKU_DEVICE_PASSWORD=my-password

プロジェクトで異なる変数名（例：ROKU_IP、ROKU_DEV_PASSWORD）を使用している場合は、env ブロックでマッピングできます。

"env": {
  "ROKU_DEVICE_HOST": "${ROKU_IP}",
  "ROKU_DEVICE_PASSWORD": "${ROKU_DEV_PASSWORD}"
}

または、既存の変数とあわせて、必要な2つの変数を .env に追加するだけです。

利用可能なツール

デプロイ

検出

ECP（外部制御プロトコル）

スクリーンショット

デバッグコンソール

ランタイム UI の編集

再デプロイせずに、実行中のサイドロード済み開発チャンネルの SceneGraph UI を編集できます。vscode-brightscript-language 拡張機能の SceneGraph Inspector が使用するものと同じバックエンドです。これらのツールは、チャンネルの On-Device Component に対して TCP ポート 9000 で roku-test-automation（RTA）プロトコルを使用するため、デバッガーを一時停止することなく変更が即座に反映されます。

仕組み。 各ツールは、実行中のチャンネルにある RTA On-Device Component（ポート 9000）への短時間の TCP 接続を開き、長さプレフィックス付きの JSON リクエスト（setValue／getValue／focusNode／…）を送信して、フレーム化された JSON レスポンスを解析します。変更はデバッガーに割り込むことなく、SceneGraph スレッドで適用されます。

ノードの指定。 nodeId には、次のいずれかを指定できます。

• RTA_1773 のような uiElementId（RTA の実行中は、すべてのノードについて roku_query_sg_nodes／roku_query_app_ui の出力に表示されます）。最も確実な指定方法です。
• チャンネルのソース内でノードに定義された実際の BrightScript id 属性。

/^RTA_\d+$/ に一致する値は RTA の base: "elementId" として送信されます。それ以外は base: "scene" として送信されます。

必須：チャンネルに RTA On-Device Component をインストールする

これらのツールは、テスト対象のチャンネルに RTA が含まれている場合にのみ動作します。方法は 2 つあります。

オプション A — サイドロードのたびに roku-debug に RTA を挿入させます（VS Code ユーザーにおすすめ）。

1. launch.json で、次を有効にします。

   "injectRdbOnDeviceComponent": true
   

2. source/main.brs で、screen.show() の直後にマーカーコメントを追加します。

   sub main()
       screen = createObject("roSGScreen")
       ' ...
       screen.show()
       ' vscode_rdb_on_device_component_entry
       ' ...
   end sub
   

オプション B — RTA コンポーネントを自分で同梱します。 roku-test-automation の device/components フォルダーをチャンネルにコピーし、シーンから RTA_OnDeviceComponent を 1 回インスタンス化します。

どちらの方法でも、インストールが成功すると、チャンネルの起動時にデバイスログに次の内容が表示されます。

[RTA][INFO] OnDeviceComponent init

ランタイム UI ツールが接続拒否エラーを返す場合、実行中のチャンネルに RTA が存在しません。上記のインストール方法のいずれかを適用し、再デプロイしてください。

BrightScript プロファイラー

Roku デバイスで生成された .bsprof ファイルを分析します。これらのツールは bsprof-cli を使用して、バイナリ形式のプロファイラーデータを解析し、構造化された JSON レポートを返します。

.bsprof ファイルを生成するには、Roku アプリの manifest でプロファイラーを有効にし（bs_prof_enabled=true）、アプリを実行して、http://<device-ip>:8080 からプロファイルをダウンロードします。

Perfetto トレース

Roku デバイスの Perfetto トレースを記録、分析、比較します。Roku OS 15.1+ が必要です。これらのツールは、ECP 制御、WebSocket による記録、PerfettoSQL による分析に roku-perfetto を使用します。

ワークフロー：トレースを有効化 → 記録を開始 → アプリを操作 → 記録を停止 → 分析。.trace ファイルは ui.perfetto.dev で開くこともできます。

ストリーム診断

ほかのあらゆる環境では再生できる HLS/DASH ストリームが Roku で再生できない原因を特定します。

fMP4/CMAF HLS で音声と映像が多重化されている（映像は再生されるが無音になる）、ハードウェアデコーダーの対応範囲を超える動画コーデックやレベル（例：4K H.264 または 8K HEVC）、トークン/403 で制限された CDN、DRM ライセンスの拒否など、Roku 固有の注意点を検出します。静的なマニフェストチェックは手がかりとして扱われます。実際のデバイスの errorInfo を指定すると、診断結果の確信度が高まります。

要件

• Node.js 18+
• 同じネットワーク上で 開発者モード を有効にした Roku デバイス
• スクリーンショットの撮影とデプロイには、サイドロードした開発用チャンネルが実行中である必要があります

ライセンス

MIT