roku MCP

年份-MCP

](https://www.npmjs.com/package/@danecodes/roku-mcp)  

MCP服务器和CLI，允许AI代理（和开发人员）与Roku设备交互。

您的编码代理可以看到Roku屏幕上的内容，发送远程控制输入，并查询设备状态——所有这些都可以通过 模型上下文协议 或者一个简单的CLI。

它的作用

• 检查UI --查询SceneGraph节点树，截取屏幕截图，使用类似CSS的选择器查找元素
• 发送输入 --遥控键、文本输入
• 发射和副载 --启动频道，深度链接到内容，部署开发版本
• 测试 --烟雾测试、飞行前证书检查、CPU采样、控制台错误监控
• 查询状态 --设备信息、媒体播放器、活动应用程序、已安装应用程序、调试控制台
• 应用程序上下文 --下降a roku-app.md 项目中的文件，每个连接的代理都会学习应用程序的导航

配置

设置您的Roku设备IP地址：

• MCP服务器： 集 ROKU_DEVICE_IP MCP配置中的环境变量（见下文）
• CLI： 使用 --device 标志（默认为 192.168.0.30)
• 屏幕截图： 集 ROKU_DEV_PASSWORD 如果您的开发密码不是 rokudev

应用程序上下文（可选）

丢一个 roku-app.md 项目根目录中的文件，教代理如何导航您的特定应用程序：

## Crunchyroll Navigation
Left-side nav menu: Home, Browse, Simulcasts, My Lists, Settings.
Press Left from any content screen to open it.
Browse has genre rows — Select a genre to see the content grid.
Search is accessible from the top of the nav menu.

MCP服务器在启动时读取此文件，并将其附加到发送给每个连接的代理的指令中。不需要配置——如果文件存在，就使用它。

要使用其他路径，请设置 ROKU_APP_CONTEXT 环境变量：

{
  "env": {
    "ROKU_APP_CONTEXT": "/path/to/my-app-context.md"
  }
}

快速开始

作为MCP服务器（Claude Code、Cursor、Windsurf等）

添加到您的 .mcp.json （项目根或 ~/.claude/.mcp.json 全球）：

{
  "mcpServers": {
    "roku": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "--package", "@danecodes/roku-mcp", "roku-mcp-server"],
      "env": {
        "ROKU_DEVICE_IP": "192.168.0.30"
      }
    }
  }
}

要自动批准所有Roku工具调用（这样您就不会每次都收到提示），请添加 ~/.claude/settings.json:

{
  "permissions": {
    "allow": ["mcp__roku"]
  }
}

作为MCP服务器（GitHub Copilot/VS代码）

Copilot需要HTTP传输。首先在终端中启动服务器：

ROKU_DEVICE_IP=192.168.0.30 npx --package @danecodes/roku-mcp roku-mcp-http
# roku-mcp HTTP server running at http://localhost:3141/mcp

然后添加到 .vscode/mcp.json 在您的项目中：

{
  "servers": {
    "roku": {
      "type": "http",
      "url": "http://localhost:3141/mcp"
    }
  }
}

在自定义端口上运行 ROKU_MCP_PORT=8888.

作为MCP服务器（OpenAI Codex CLI）

添加 ~/.codex/config.toml （全球）或 .codex/config.toml （项目范围）：

[mcp_servers.roku]
command = "npx"
args = ["-y", "--package", "@danecodes/roku-mcp", "roku-mcp-server"]

[mcp_servers.roku.env]
ROKU_DEVICE_IP = "192.168.0.30"

您的代理现在拥有以下工具：

设备控制

试运行器（左移）

代理效率

左移质量门

作为CLI

# Inspect the UI tree
npx roku-mcp ui tree --device 192.168.0.30
npx roku-mcp ui tree --depth 4
npx roku-mcp ui tree --all-attrs

# Find specific elements
npx roku-mcp ui find "HomePage HomeHeroCarousel"
npx roku-mcp ui find "AppLabel" --all-attrs

# See what's focused, what screen you're on, or get raw XML
npx roku-mcp ui focused
npx roku-mcp ui screen
npx roku-mcp ui source

# Take a screenshot
npx roku-mcp ui screenshot -o screen.png

# Send key presses
npx roku-mcp press Select
npx roku-mcp press Down --times 3 --delay 200

# Type text
npx roku-mcp type "search query"

# Launch apps
npx roku-mcp launch dev
npx roku-mcp launch dev --params '{"contentId":"12345","mediaType":"episode"}'

# Device info
npx roku-mcp info device
npx roku-mcp info app
npx roku-mcp info apps
npx roku-mcp info player

# Debug console
npx roku-mcp console log
npx roku-mcp console log --filter "error"
npx roku-mcp console send bt

# Test runner
npx roku-mcp test sideload-watch ./build.zip --duration 30000
npx roku-mcp test smoke --content-id GG5H5XQ7R --media-type episode
npx roku-mcp test cert-preflight
npx roku-mcp test chanperf --duration 15000 --threshold 70
npx roku-mcp test wait "HomeScreen" --timeout 10000
npx roku-mcp test assert "#playButton" --assertion focused

作为一个图书馆

ECP客户端单独发布为 @danecodes/roku-ecp --如果你想用自己的代码控制Roku设备，请使用它：

import { EcpClient, Key, parseUiXml, findElement } from '@danecodes/roku-ecp';

const roku = new EcpClient('192.168.0.30');

// Send keys
await roku.press(Key.Down, { times: 3 });
await roku.press(Key.Select);

// Inspect the UI
const xml = await roku.queryAppUi();
const tree = parseUiXml(xml);
const button = findElement(tree, 'AppButton#play_button');
console.log(button?.attrs.focused); // "true"
console.log(button?.attrs.text);    // "Play"

// Query state
const player = await roku.queryMediaPlayer();
const app = await roku.queryActiveApp();

选择器语法

使用类似CSS的选择器对SceneGraph节点名称查找元素：

烟雾测试演示

将编码代理指向开发版本，它将进行侧载、测试和报告——对输出进行截图并将其发送给您的经理。

You: Sideload the build at ./target/crunchyroll-dev.zip and run a smoke test.
     Deep link to content ID "GG5H5XQ7R" (episode) and verify playback starts.

Agent: I'll sideload the build and watch the console for errors first.

  → roku_sideload_and_watch(zip_path: "./target/crunchyroll-dev.zip", duration: 30000)

  {
    "passed": true,
    "message": "PASS: Install Success — no errors in 30s of console output",
    "sideload_result": "Install Success",
    "errors": [],
    "crashes": [],
    "exceptions": []
  }

Agent: Clean install. Now running the smoke test with playback verification.

  → roku_smoke_test(
      content_id: "GG5H5XQ7R",
      media_type: "episode",
      ui_timeout: 15000,
      playback_timeout: 30000
    )

  {
    "passed": true,
    "message": "PASS: App launched, UI rendered, and playback started",
    "steps": [
      { "name": "launch",     "passed": true, "message": "Deep linked to \"GG5H5XQ7R\" in channel dev" },
      { "name": "ui_visible", "passed": true, "message": "UI rendered after 2340ms", "elapsed_ms": 2340 },
      { "name": "playback",   "passed": true, "message": "Player reached \"play\" after 8710ms", "elapsed_ms": 8710 }
    ],
    "player_state": {
      "state": "play",
      "error": false,
      "position": "00:00:08",
      "duration": "00:42:17"
    }
  }

Agent: All green. Build sideloaded cleanly, UI rendered in 2.3s, playback started in 8.7s.

所有测试命令在失败时都会以代码1退出，使其对CI友好。

在聊天中使用它

您可以通过AI助手与Roku对话。代理使用MCP工具导航、检查和截图设备：

You: Go to the browse screen, select the Action genre, and take a screenshot for me

Agent: I'll take a screenshot to see where we are first.

  → roku_screenshot()

Agent: We're on the Home screen. I'll open the nav menu and find Browse.

  → roku_press_key(key: "Left")
  → roku_screenshot()

Agent: Nav menu is open. Browse is two items down.

  → roku_press_key(key: "Down", times: 2)
  → roku_press_key(key: "Select")
  → roku_screenshot()

Agent: We're on Browse. I can see genre rows — Action is 4 rows down.

  → roku_press_key(key: "Down", times: 4)
  → roku_press_key(key: "Select")
  → roku_screenshot(save_path: "./screenshots/action_genre.png")

Agent: Done — screenshot saved. We're on the Action genre grid.

代理通过截图查看屏幕，决定按下什么键，并验证结果——所有这些都是通过自然对话完成的。

运作原理

关键端点是 GET /query/app-ui 它以XML格式返回完整的SceneGraph节点树。roku-ecp解析该XML，并允许您使用类似CSS的选择器进行查询。

需求

• 同一网络上处于开发者模式的Roku设备
• Node.js 18+

许可证

麻省理工学院