roku-mcp

A Model Context Protocol (MCP) server for Roku device automation. Exposes tools for app deployment, ECP remote control, screenshot capture, SceneGraph node inspection, and BrightScript debug console access.

Install

The server ships as a single npx command. Install once globally if you prefer, or let your MCP client launch it on demand via npx -y roku-mcp — both work.

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

Configure your AI client below. Every platform uses the same launch line; only the config file and reload step change.

{
  "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 rules

For better agent behavior (the observe → act → wait → verify loop, the RTA uiElementId gotcha that silently breaks roku_edit_node, when to use which tool), the repo ships drop-in rules pre-formatted for each major agent. The body is identical — only the wrapper differs to match what each agent auto-loads.

See rules/README.md for one-line copy commands per agent.

Quickstart

Once your client is wired up, these three prompts work out of the box and exercise the main capability groups.

1. Confirm the device is reachable

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

The agent should call roku_query_device_info (and possibly roku_discover if no host is configured) and reply in one turn.

2. Drive the UI with screenshots

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

This exercises roku_keypress, roku_sleep, and roku_screenshot — the standard observe → act → wait → verify loop.

3. Live-edit a running channel (requires RTA — see Runtime UI Editing)

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.

The agent will roku_query_app_ui to locate the node, grab the uiElementId, call roku_edit_node + roku_get_value, and roll back — proving end-to-end RTA wiring.

Environment Variables

Both can also be passed as parameters on each tool call, which override the environment variables.

Auto-discovery

If ROKU_DEVICE_HOST is not set and no host parameter is provided, the server automatically discovers Roku devices on the local network using SSDP and uses the first one found. You can also use the roku_discover tool to list all available devices. Note that the password cannot be discovered and must still be configured.

.env file support

The server automatically loads a .env file from the current working directory using dotenv. If your project's .env already uses ROKU_DEVICE_HOST and ROKU_DEVICE_PASSWORD, the server picks them up with no extra configuration — just omit the env block from your MCP config:

ROKU_DEVICE_HOST=192.168.1.100
ROKU_DEVICE_PASSWORD=my-password

If your project uses different variable names (e.g. ROKU_IP, ROKU_DEV_PASSWORD), you can map them in the env block:

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

Or simply add the two expected variables to your .env alongside your existing ones.

Available Tools

Deploy

Discovery

ECP (External Control Protocol)

Screenshot

Debug Console

Runtime UI Editing

Edit the SceneGraph UI of a running sideloaded dev channel without redeploying — the same backend the SceneGraph Inspector in the vscode-brightscript-language extension uses. These tools speak the roku-test-automation (RTA) protocol against the channel's On-Device Component on TCP port 9000, so changes apply instantly with no debugger pause.

How it works. Each tool opens a short-lived TCP connection to the RTA On-Device Component (port 9000) in the running channel, sends a length-prefixed JSON request (setValue / getValue / focusNode / ...) and parses the framed JSON response. Mutations apply on the SceneGraph thread without breaking into the debugger.

Node addressing. nodeId accepts either:

• A uiElementId like RTA_1773 (visible in the roku_query_sg_nodes / roku_query_app_ui output for every node when RTA is running). This is the most robust target.
• A real BrightScript id attribute defined on the node in the channel source.

Anything matching /^RTA_\d+$/ is sent with RTA base: "elementId"; otherwise it's sent with base: "scene".

Required: install the RTA On-Device Component in your channel

These tools only work when the channel under test bundles RTA. You have two options:

Option A — let roku-debug inject RTA on every sideload (recommended for VS Code users).

1. In your launch.json, enable:

   json

   "injectRdbOnDeviceComponent": true
   

2. In source/main.brs, add the marker comment immediately after screen.show():

   brightscript

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

Option B — bundle the RTA component yourself. Copy the device/components folder from roku-test-automation into your channel and instantiate RTA_OnDeviceComponent once from your scene.

Either way, on a successful install you will see this in the device log at channel launch:

[RTA][INFO] OnDeviceComponent init

If a runtime UI tool returns a connection-refused error, RTA is not present in the running channel — apply one of the two install options above and redeploy.

BrightScript Profiler

Analyze .bsprof files generated by Roku devices. These tools use bsprof-cli to parse the binary profiler format and return structured JSON reports.

To generate a .bsprof file, enable the profiler in your Roku app's manifest (bs_prof_enabled=true), run the app, and download the profile from http://<device-ip>:8080.

Perfetto Tracing

Record, analyze, and compare Perfetto traces from Roku devices. Requires Roku OS 15.1+. These tools use roku-perfetto for ECP control, WebSocket recording, and PerfettoSQL analysis.

Workflow: enable tracing → start recording → interact with app → stop recording → analyze. The .trace files can also be opened at ui.perfetto.dev.

Stream Diagnosis

Figure out why an HLS/DASH stream that plays everywhere else fails on Roku.

It detects Roku-specific gotchas such as muxed audio+video in fMP4/CMAF HLS (plays video but silent), video codecs/levels beyond the hardware decoder (e.g. 4K H.264 or 8K HEVC), token/403-gated CDNs, and DRM license rejections. The static manifest checks are treated as hints; when you supply the real device errorInfo the diagnosis is corroborated to high confidence.

Requirements

• Node.js 18+
• A Roku device with Developer Mode enabled on the same network
• For screenshots and deploy: a sideloaded dev channel must be running

License

MIT