roku-mcp

MCP server and CLI that lets AI agents (and developers) interact with Roku devices.

Your coding agent can see what's on the Roku screen, send remote control input, and query device state — all through the Model Context Protocol or a simple CLI.

What it does

• Inspect the UI — query the SceneGraph node tree, take screenshots, find elements with CSS-like selectors
• Send input — remote control keys, text entry
• Launch and sideload — start channels, deep link to content, deploy dev builds
• Test — smoke tests, cert preflight checks, CPU sampling, console error monitoring
• Query state — device info, media player, active app, installed apps, debug console
• App context — drop a roku-app.md file in your project and every connected agent learns your app's navigation

Configuration

Set your Roku device IP address:

• MCP server: Set ROKU_DEVICE_IP environment variable in your MCP config (see below)
• CLI: Use --device <ip> flag (defaults to 192.168.0.30)
• Screenshots: Set ROKU_DEV_PASSWORD if your dev password isn't rokudev

App context (optional)

Drop a roku-app.md file in your project root to teach agents how to navigate your specific app:

## 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.

The MCP server reads this file at startup and appends it to the instructions sent to every connected agent. No config needed — if the file exists, it's used.

To use a different path, set the ROKU_APP_CONTEXT environment variable:

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

Quick start

As an MCP server (Claude Code, Cursor, Windsurf, etc.)

Add to your .mcp.json (project root or ~/.claude/.mcp.json for global):

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

To auto-approve all Roku tool calls (so you don't get prompted each time), add to ~/.claude/settings.json:

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

As an MCP server (GitHub Copilot / VS Code)

Copilot requires the HTTP transport. Start the server in a terminal first:

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

Then add to .vscode/mcp.json in your project:

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

Run on a custom port with ROKU_MCP_PORT=8888.

As an MCP server (OpenAI Codex CLI)

Add to ~/.codex/config.toml (global) or .codex/config.toml (project-scoped):

[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"

Your agent now has these tools:

Device control

| Tool | Description | |------|-------------| | roku_ui_tree | Get the full SceneGraph UI tree — see what's on screen | | roku_find_element | Find elements by CSS-like selector | | roku_press_key | Send remote control key press (Select, Up, Down, etc.) | | roku_type_text | Type text into keyboard inputs | | roku_screenshot | Take a screenshot, optionally save to disk | | roku_launch | Launch a channel with optional deep link params | | roku_deep_link | Deep link directly into content by ID | | roku_close_app | Close the running app (press Home) | | roku_sideload | Deploy a .zip package to the device | | roku_device_info | Get device model, software version, network info | | roku_active_app | Get the currently running app | | roku_media_player | Get playback state (position, duration, format) | | roku_installed_apps | List all installed channels | | roku_console_log | Read BrightScript debug console output (errors, print statements, crashes) | | roku_console_command | Send debug commands (bt, var, cont, step, over, out) | | roku_volume | Volume up, down, or mute | | roku_input | Send custom input parameters to the running app |

Test runner (Shift Left)

| Tool | Description | |------|-------------| | roku_wait_for | Poll until a selector appears on screen with configurable timeout — use after navigation | | roku_assert_element | Assert an element exists, is focused, or has a specific attribute value — returns pass/fail JSON | | roku_sideload_and_watch | Sideload a zip + watch console for errors/crashes — returns CI-ready pass/fail report | | roku_smoke_test | Launch app, verify UI renders, optionally verify playback — full pass/fail with step detail |

Agent efficiency

| Tool | Description | |------|-------------| | roku_focused_element | Return only the currently focused element — token-efficient alternative to full tree scan | | roku_screen_name | Infer the current screen name from the SceneGraph root component | | roku_console_watch | Monitor console for a pattern match during a time window — pass/fail with matching lines |

Shift Left quality gates

| Tool | Description | |------|-------------| | roku_cert_preflight | Run Roku cert failure checklist (back nav, Home exit, relaunch, error scan) | | roku_chanperf_sample | Sample CPU usage via chanperf for a configurable duration — high watermark + pass/fail |

As a 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

As a library

The ECP client is published separately as @danecodes/roku-ecp — use that if you want to control Roku devices from your own code:

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();

Selector syntax

Find elements using CSS-like selectors against SceneGraph node names:

| Selector | Matches | |----------|---------| | HomePage | Node with tag HomePage | | AppButton#play_button | AppButton with name="play_button" | | #titleLabel | Any node with name="titleLabel" | | HomePage HomeHeroCarousel | HomeHeroCarousel anywhere inside HomePage | | LayoutGroup > AppLabel | AppLabel that is a direct child of LayoutGroup | | AppButton:nth-child(1) | First AppButton among siblings | | CollectionModule + CollectionModule | CollectionModule immediately after another | | A ~ B | General sibling — all B after A | | [focused="true"] | Attribute value match | | [text*="Log"] | Attribute contains substring | | [text^="Episode"] | Attribute starts with | | [uri$=".png"] | Attribute ends with | | [visible] | Attribute exists | | AppButton:has(AppLabel[text="Play"]) | Parent that contains a matching child | | AppButton:not([focused="true"]) | Negation | | :first-child, :last-child, :only-child | Positional pseudo-classes | | :empty | Nodes with no children | | LinearCard, SlantedCard | Comma groups — match either | | * | Universal — matches any node |

Smoke test demo

Point a coding agent at a dev build and it will sideload, test, and report — screenshot the output and send it to your manager.

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.

All test commands exit with code 1 on failure, making them CI-friendly.

Using it in chat

You can talk to your Roku through your AI assistant. The agent uses the MCP tools to navigate, inspect, and screenshot the device:

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.

The agent takes screenshots to see the screen, decides what keys to press, and verifies the result — all through natural conversation.

How it works

Roku devices expose an HTTP API called ECP (External Control Protocol) on port 8060. roku-mcp uses @danecodes/roku-ecp to call ECP endpoints directly — no WebDriver, no Appium, no Selenium, no Java.

The key endpoint is GET /query/app-ui which returns the full SceneGraph node tree as XML. roku-ecp parses that XML and lets you query it with CSS-like selectors.

Requirements

• A Roku device in developer mode on the same network
• Node.js 18+

License

MIT