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.

Installation

npm install -g roku-mcp

Or run directly with npx (no install required):

npx roku-mcp

Client Configuration

Cursor

1. Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "roku": {
      "command": "npx",
      "args": ["-y", "roku-mcp"],
      "env": {
        "ROKU_DEVICE_HOST": "192.168.1.XXX",
        "ROKU_DEVICE_PASSWORD": "your-password"
      }
    }
  }
}

2. Reload the window: Cmd+Shift+P (macOS) / Ctrl+Shift+P (Windows/Linux) → Developer: Reload Window
3. Go to Cursor Settings → MCP and verify the "roku" server shows a green status. If it appears disabled, click the toggle to enable it.

VS Code

Requires VS Code 1.99+ with the GitHub Copilot extension.

1. Create .vscode/mcp.json in your project root:

{
  "servers": {
    "roku": {
      "command": "npx",
      "args": ["-y", "roku-mcp"],
      "env": {
        "ROKU_DEVICE_HOST": "192.168.1.XXX",
        "ROKU_DEVICE_PASSWORD": "your-password"
      }
    }
  }
}

2. Reload the window: Cmd+Shift+P / Ctrl+Shift+P → Developer: Reload Window
3. Open Copilot Chat and switch to Agent mode (select from the chat mode dropdown). The roku tools will be available there.

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "roku": {
      "command": "npx",
      "args": ["-y", "roku-mcp"],
      "env": {
        "ROKU_DEVICE_HOST": "192.168.1.XXX",
        "ROKU_DEVICE_PASSWORD": "your-password"
      }
    }
  }
}

Restart Claude Desktop after saving.

Windsurf

Create .windsurf/mcp.json in your project root:

{
  "mcpServers": {
    "roku": {
      "command": "npx",
      "args": ["-y", "roku-mcp"],
      "env": {
        "ROKU_DEVICE_HOST": "192.168.1.XXX",
        "ROKU_DEVICE_PASSWORD": "your-password"
      }
    }
  }
}

Reload the window after saving.

Any MCP-compatible client

The server uses stdio transport. Any client that supports MCP can launch it with:

command: npx
args:    ["-y", "roku-mcp"]

Pass ROKU_DEVICE_HOST and ROKU_DEVICE_PASSWORD as environment variables, or omit the host to use SSDP auto-discovery.

Environment Variables

Variable	Description
ROKU_DEVICE_HOST	IP address or hostname of the Roku device
ROKU_DEVICE_PASSWORD	Developer password for the Roku device

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

Tool	Description
roku_deploy	Sideload (deploy) a Roku app to the device
roku_delete_dev_channel	Delete the currently sideloaded developer channel

Discovery

Tool	Description
roku_discover	Scan the local network for Roku devices via SSDP

ECP (External Control Protocol)

Tool	Description
roku_keypress	Send a single key press (Home, Select, Up, Down, Left, Right, Back, etc.)
roku_keypress_sequence	Send multiple key presses in sequence with configurable delay
roku_type_text	Type a text string into the focused field (e.g. email, password, search)
roku_launch	Launch or deep-link into a channel
roku_query_device_info	Get device model, firmware, serial number, network info
roku_query_active_app	Get the currently running app
roku_query_media_player	Get media player state (play/pause/buffer/stop), position, and duration
roku_query_app_ui	Get the current app UI tree as XML
roku_query_sg_nodes	Query SceneGraph nodes (all, roots, or by node ID)
roku_find_node	Search the UI tree for a node by ID or attribute (subtype, text, etc.)
roku_get_focused_node	Get the currently focused node with all its properties
roku_sleep	Wait for a specified duration (useful between navigation steps)

Screenshot

Tool	Description
roku_screenshot	Capture a screenshot (returns base64 image and file path)

Debug Console

Tool	Description
roku_console_connect	Open a TCP connection to the BrightScript debug console (port 8085)
roku_console_read	Read buffered console output and auto-disconnect
roku_console_send	Send a command to the debug console and auto-disconnect
roku_console_disconnect	Close the console connection (safety net)

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.

Tool	Description
analyze_bsprof	Analyze a .bsprof file — memory leaks, CPU hot paths, full report, or summary. Supports filtering by module/file and sorting options.
compare_bsprof	Compare two .bsprof profiles to detect regressions, improvements, new leaks, and resolved leaks.
bsprof_info	Get header metadata (target name, device, firmware, format version, features) without full parsing.

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.

Tool	Description
roku_perfetto_enable	Enable Perfetto tracing for a channel via ECP (tracing starts on next app launch)
roku_perfetto_start	Start recording a Perfetto trace via WebSocket binary stream
roku_perfetto_stop	Stop recording and return file path, size, and duration
analyze_perfetto	Analyze a .trace file — summary, frame-drops, key-events, observers, rendezvous, set-fields, or threads. Returns AI-friendly structured JSON with suggestions.
compare_perfetto	Compare two .trace files to detect performance regressions and improvements
query_perfetto	Run a raw PerfettoSQL query against a trace file for custom analysis

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

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