# RokuMCP [Health: Active]

**Category:** 🏠 Home Automation  
**Repository:** https://github.com/jack1590/RokuMCP  
**GitHub Stars:** 4  
**npm Downloads (last month):** 715  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/rokumcp

## Description
MCP server for Roku device automation — deploy, ECP control, screenshots, and debug console

## Tools
Capabilities this server exposes over MCP:

- **roku_deploy** — Sideload (deploy) a Roku application to the device. Packages all files in the project directory and uploads them. A dev channel must not already be running, or it will be replaced.
- **roku_delete_dev_channel** — Delete the currently sideloaded developer channel from the Roku device.
- **roku_discover** — Scan the local network for Roku devices using SSDP discovery. Returns a list of all found devices with their IP addresses.
- **roku_keypress** — Send a single key press to the Roku device via ECP. Common keys: Home, Rev, Fwd, Play, Select, Left, Right, Down, Up, Back, InstantReplay, Info, Backspace, Search, Enter, Lit_<character>
- **roku_keypress_sequence** — Send a sequence of key presses to the Roku device with an optional delay between each press.
- **roku_launch** — Launch or deep-link into a channel on the Roku device. Use appId "dev" for the sideloaded developer channel.
- **roku_query_device_info** — Query the Roku device for its info: model, firmware version, serial number, network info, etc.
- **roku_query_active_app** — Query the currently active (foreground) app on the Roku device.
- **roku_query_app_ui** — Get the current app UI tree as XML. Only works when a sideloaded dev channel is running.
- **roku_query_sg_nodes** — Query SceneGraph nodes on the Roku device. Use type "all" for all nodes, "roots" for root nodes, or "node" with a nodeId to inspect a specific node.
- **roku_type_text** — Type a text string into the currently focused text field on the Roku device. Each character is sent as an individual Lit_ keypress. Use this for search fields, email inputs, password fields, etc.
- **roku_query_media_player** — Query the media player state on the Roku device. Returns playback state (play, pause, buffer, stop, none), position, duration, and error info. Use this to verify video playback in tests.
- **roku_find_node** — Search the app UI tree for a node by its ID or attribute value. Returns the matching node with all its properties (text, visible, focused, subtype, bounds, etc.). Only works when a sideloaded dev channel is running.
- **roku_get_focused_node** — Get the currently focused node in the app UI tree. Returns the node with all its properties (id, subtype, text, bounds, etc.). Only works when a sideloaded dev channel is running.
- **roku_sleep** — Wait for a specified duration. Use this between navigation steps to allow the UI to render, animations to complete, or content to load.
- **roku_screenshot** — Capture a screenshot of the current screen on the Roku device. A sideloaded dev channel must be running. Returns the image as base64-encoded content and the file path where it was saved.
- **roku_console_connect** — Open a persistent TCP connection to the BrightScript debug console on port 8085. Only one connection is active at a time.
- **roku_console_read** — Read buffered output from the BrightScript debug console since the last read. Automatically disconnects after reading.
- **roku_console_send** — Send a command to the BrightScript debug console and return the response. Automatically disconnects after receiving the response. Common commands: bt (backtrace), var (variables), cont (continue), step, over, out, exit, print <expr>.
- **roku_console_disconnect** — Close the active BrightScript debug console connection.
- **roku_console_capture_start** — Start recording the BrightScript debug console (port 8085) to a file, keeping the connection open until roku_console_capture_stop. Output from before the capture (the console replays the previous session on connect) is skipped. Console text is never returned; use roku_console_wait to detect lines. Port 8085 accepts a single client: detach the VS Code BrightScript debugger first.
- **roku_console_wait** — Wait until a console line matching a regex appears in the active capture (see roku_console_capture_start). Returns line number, timestamp and a short redacted preview; the full line is in the capture file. Resolves early with reason "waiting_for_debugger" if the channel is blocked waiting for the VS Code debugger (redeploy it with roku_deploy).
- **roku_console_capture_stop** — Stop the active console capture, flush and close the file. Returns file path, bytes and line count.
- **roku_console_capture_status** — Report whether a console capture is active, its file, bytes and line count.
- **analyze_bsprof** — Analyze a BrightScript Profiler (.bsprof) file from a Roku device. Supports memory leak detection, CPU hot-path analysis, combined full reports, and one-page summaries. Returns structured JSON.
- **compare_bsprof** — Compare two BrightScript Profiler (.bsprof) files to detect regressions, improvements, new memory leaks, resolved leaks, and CPU time deltas between runs.
- **bsprof_info** — Get header metadata from a .bsprof file without full analysis — target name, device model, firmware, format version, duration, file size, and enabled features. Reads only the header/footer, so it is instant even on multi-hundred-MB profiles.
- **roku_perfetto_enable** — Enable Perfetto tracing for a Roku channel via ECP. Tracing starts automatically on each app launch. Requires Roku OS 15.1+. There is no disable command — enabled channels are cleared on reboot.
- **roku_perfetto_start** — Start recording a Perfetto trace from the Roku device. Opens a binary WebSocket to stream trace data to a local file. Only one recording session at a time. Call roku_perfetto_enable first.
- **roku_perfetto_stop** — Stop the active Perfetto trace recording. Returns the file path, size, and duration. The resulting .trace file can be opened at https://ui.perfetto.dev/ or analyzed with analyze_perfetto.
- **analyze_perfetto** — Analyze a Roku Perfetto trace file (.trace). Returns structured JSON with AI-friendly suggestion fields for each analysis area. Requires the trace_processor binary (auto-downloaded on first use). Modes: summary (full report), frame-drops, key-events, observers, rendezvous, set-fields, threads.
- **compare_perfetto** — Compare two Roku Perfetto trace files to detect performance regressions and improvements. Returns metric deltas for frame drops, key events, observers, rendezvous, and setField calls.
- **query_perfetto** — Run a raw PerfettoSQL query against a Roku Perfetto trace file. Use for custom analysis beyond the built-in modes. Common queries: SELECT * FROM slice WHERE name = 'swapBuffers' ORDER BY dur DESC; SELECT * FROM slice WHERE name = 'keyEvent' ORDER BY dur DESC;
- **roku_edit_node** — Edit a SceneGraph node on the running dev channel at runtime by setting one or more fields. Uses the roku-test-automation (RTA) On-Device Component on TCP port 9000 — the same backend the SceneGraph Inspector in the vscode-brightscript-language extension uses. Requires RTA to be present in the running channel (see README "Runtime UI Editing"). nodeId can be either a `uiElementId` like "RTA_1773" (as shown by roku_query_sg_nodes) or a BrightScript scene-level `id`. Common fields: visible (boolean), translation ([x,y]), text (string), color (hex like "0xRRGGBBAA"), opacity (number 0..1).
- **roku_set_node_visible** — Show or hide a SceneGraph node by id via RTA setValue on the `visible` field.
- **roku_move_node** — Move a SceneGraph node to a new position by setting its `translation` field to [x, y].
- **roku_focus_node** — Set focus on a SceneGraph node by id via RTA focusNode.
- **roku_remove_node** — Remove a SceneGraph node from its parent at runtime via RTA removeNode.
- **roku_create_node** — Create a new SceneGraph node at runtime and append it as a child of an existing node via RTA createChild. Subtype must be a SceneGraph node type registered for the running scene (e.g. Label, Rectangle, Poster, Group).
- **roku_get_value** — Read a field value from a SceneGraph node at runtime via RTA getValue. Returns the value as JSON. Pass either nodeId+field, or a full keyPath like "MainScene.rowList.0.title".
- **roku_observe_field** — Wait for a SceneGraph field to change (or match a specific value) via RTA onFieldChangeOnce. Returns when the observer fires or the timeout elapses. Great for "wait until video starts playing" style assertions.
- **roku_diagnose_stream** — Diagnose why an HLS/DASH stream fails on Roku specifically by correlating the evidence you already have. Provide any combination of: the Video node error the device reported (errorInfo, as JSON or pasted log text), the manifest (a url to fetch, or pasted m3u8/mpd content), and a Charles/HAR HTTP capture file. The tool cross-references them into ranked root-cause findings (e.g. "errorCode -6 DRM + a 403 license POST = license server rejected the Roku request"). No Roku device is required for this. Optionally set captureLive=true (with host+password) to deploy a bundled StreamProbe harness and capture the device error first when you do not have errorInfo yet.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "rokumcp": {
    "command": "npx",
    "args": ["-y","roku-mcp"],
    "env": {
      "ROKU_DEVICE_HOST": "",
      "ROKU_DEVICE_PASSWORD": ""
    }
  }
}
```

**Requires environment variables:** `ROKU_DEVICE_HOST`, `ROKU_DEVICE_PASSWORD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What RokuMCP MCP server does

RokuMCP MCP server exposes Roku device operations as MCP tools for an AI client. It can discover devices on the local network, retrieve device and application state, control navigation, launch channels, enter text, and capture screenshots. The tool set also covers developer workflows: deploying or removing a sideloaded channel, reading the running UI as XML, inspecting SceneGraph nodes, and interacting with the BrightScript debug console.

Runtime UI editing tools can change node fields, visibility, position, focus, and hierarchy while a channel is running. Agents can read values, wait for field changes, and use node searches to build an observe, act, wait, and verify workflow. Separate profiling tools analyze `.bsprof` files for memory and CPU findings or compare two profiles for regressions and improvements.

## How it works

The server communicates with MCP clients over stdio. A client launches it with `npx -y roku-mcp`, after which the available `roku_*` and profiling tools can be called. Device operations use a Roku host and, where required, the developer password. Host and password values may be supplied through the process environment or passed on individual tool calls; call-level values override the environment configuration.

If no host is supplied, the server uses SSDP to find Roku devices on the local network and selects the first result. The `roku_discover` tool can list devices explicitly. Passwords are not discovered automatically. Console operations connect to the Roku BrightScript debug console on TCP port 8085, while app and remote-control operations use the Roku device interfaces supported by the tool.

## Setup and configuration

Install the package globally with npm or let the MCP client fetch it on demand:

```bash
npm install -g roku-mcp
```

A client configuration needs the `npx` command and `-y roku-mcp` arguments. `ROKU_DEVICE_HOST` can contain a Roku IP address or hostname, and `ROKU_DEVICE_PASSWORD` contains the device developer password. Both variables are optional at process startup if equivalent values are provided on tool calls; omitting the host enables SSDP discovery. The server also loads these variables from a `.env` file in the current working directory.

The documented client configurations cover Cursor, VS Code with GitHub Copilot Agent mode, Claude Desktop, Windsurf, and other MCP-compatible clients. Node.js 18+ and an available `npx` command are required by the documented launch setup. After changing configuration, reload or restart the client as appropriate and verify that the Roku tools are listed.

## Tools and capabilities

- Discover Roku devices and query model, firmware, serial, and network information.
- Send individual or sequenced remote-control keys, type text, launch channels, and wait between actions.
- Read the active app, media-player state, app UI XML, focused node, and SceneGraph nodes.
- Capture screenshots and search nodes by ID or attributes such as subtype or text.
- Deploy or delete a developer channel and connect to, read from, send commands to, or disconnect from the BrightScript console.
- Edit runtime node fields, visibility, position, focus, parentage, and creation; read values and observe field changes.
- Analyze or compare BrightScript profiler files for leaks, hot paths, and performance changes.

## Limitations and notes

RokuMCP MCP server is intended for Roku devices reachable from the machine running the MCP client. Automatic discovery depends on local-network SSDP visibility, and the developer password still must be supplied separately. Runtime node editing depends on the relevant Roku runtime tooling and requires the running channel to expose the nodes being targeted.

The README recommends following an observe-before-action workflow for UI automation and notes that runtime editing may require the node's `uiElementId`. Console access uses port 8085, so network access and device-side debugging availability affect those tools. The server is documented as a stdio service rather than a hosted HTTP endpoint.

_Full upstream README: https://allmcps.com/mcp/rokumcp/readme_