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: "..." }

Agent 规则

为了让 Agent 更好地运行（observe → act → wait → verify 循环、会导致 roku_edit_node 静默失效的 RTA uiElementId 陷阱，以及何时使用哪种工具），仓库提供了适用于各大 Agent 的即用型规则。规则正文相同，只有外层格式不同，以匹配各 Agent 的自动加载方式。

请参阅 rules/README.md，查看每个 Agent 对应的一行复制命令。

快速开始

配置好客户端后，以下三个提示词可开箱即用，并涵盖主要功能组。

1. 确认设备可连接

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

Agent 应调用 roku_query_device_info（如果未配置主机，也可能调用 roku_discover），并在一轮对话中回复。

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.

Agent 将调用 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}"
}

或者，只需将这两个预期变量添加到 .env 中，并保留现有变量。

可用工具

部署

设备发现

ECP（外部控制协议）

截图

调试控制台

运行时 UI 编辑

无需重新部署，即可编辑正在运行的侧载开发频道的 SceneGraph UI——使用的后端与 vscode-brightscript-language 扩展中的 SceneGraph Inspector 相同。这些工具通过 TCP 端口 9000，使用 roku-test-automation（RTA）协议与频道的设备端组件通信，因此更改会立即生效，且不会暂停调试器。

工作原理。 每个工具都会与正在运行的频道中的 RTA 设备端组件（端口 9000）建立一个短暂的 TCP 连接，发送带长度前缀的 JSON 请求（setValue / getValue / focusNode / ...），并解析带帧的 JSON 响应。更改会直接应用于 SceneGraph 线程，不会中断进入调试器。

节点寻址。 nodeId 接受以下任一种形式：

• 类似 RTA_1773 的 uiElementId（RTA 运行时，roku_query_sg_nodes / roku_query_app_ui 的输出中会显示每个节点的此 ID）。这是最可靠的目标。
• 在频道源代码的节点上定义的真实 BrightScript id 属性。

所有符合 /^RTA_\d+$/ 的值都会以 RTA base: "elementId" 发送；否则会以 base: "scene" 发送。

必需：在频道中安装 RTA 设备端组件

只有在被测频道打包了 RTA 时，这些工具才能工作。你有两种选择：

选项 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。

无论采用哪种方式，成功安装后，频道启动时都会在设备日志中看到以下内容：

[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+。这些工具使用 roku-perfetto 进行 ECP 控制、WebSocket 录制和 PerfettoSQL 分析。

工作流：启用跟踪 → 开始录制 → 与应用交互 → 停止录制 → 分析。.trace 文件也可以在 ui.perfetto.dev 中打开。

流诊断

找出为什么能在其他地方播放的 HLS/DASH 流在 Roku 上无法播放。

它可检测 Roku 特有的常见问题，例如 fMP4/CMAF HLS 中复用的音频+视频（有画面但无声音）、超出硬件解码器能力的视频编解码器/级别（如 4K H.264 或 8K HEVC）、受令牌/403 限制的 CDN，以及 DRM 许可证拒绝。静态清单检查仅作为提示；提供真实设备的 errorInfo 后，诊断结果可获得高置信度佐证。

要求

• Node.js 18+
• 在同一网络上启用了 开发者模式 的 Roku 设备
• 如需截屏和部署，必须正在运行侧载的开发频道

许可证

MIT