Roku

You can run a Roku MCP Server to enable AI agents to develop, test, and certify Roku devices by directly controlling and querying the device through a structured MCP setup. This server streamlines app deployment, device verification, input handling, logging, and comprehensive test flows to accelerate certification and QA work.

How to use

You interact with the MCP server by configuring an MCP client in your AI agent. The client points to the Roku MCP server configuration and uses the available tools to perform practical tasks such as deploying apps, capturing screenshots, verifying display capabilities, driving remote inputs, inspecting SceneGraph data, monitoring streaming state, and running integrated test sequences.

How to install

git clone https://github.com/maskelog/roku-mcp.git
cd roku-mcp
npm install
npm run build

Configuration and usage notes

Prepare your environment by creating a local configuration file and enabling Developer Mode on your Roku device. You will specify the device IP, Developer Mode password, and optional project/server URLs. The following example shows the essential configuration steps used to connect the MCP client to the Roku MCP server.

ROKU_DEV_HOST=192.168.0.100     # Roku device IP (Settings > Network > About)
ROKU_DEV_PASSWORD=your_password  # Developer Mode password
ROKU_PROJECT_ROOT=               # Project root (default: parent directory)
ROKU_APP_SERVER_URL=             # App server URL (optional)

Ensure Roku Developer Mode is enabled on the target device.

## MCP client setup and usage

Add the MCP server configuration to your AI agent’s setup. This example defines a local MQTT-like MCP entry that runs the MCP server locally using Node.js and points to the compiled distribution. Replace the path with your actual build location and credentials.

{ "mcpServers": { "roku-dev": { "command": "node", "args": ["/path/to/roku-mcp/dist/index.js"], "env": { "ROKU_DEV_HOST": "192.168.0.100", "ROKU_DEV_PASSWORD": "your_password" } } } }

This configuration enables the MCP client to communicate with the Roku MCP server and perform the listed tools.

Usage examples

Ask your agent to perform common tasks using natural language. The following are representative actions your agent can perform through MCP tools.

• Show me the Roku device info to confirm model and firmware details.
• Deploy the app and capture a screenshot to verify successful sideload and visuals.
• Check if the ad framework is set up correctly (RAF).
• Verify HD/FHD resolution support on the target device.
• Run a full integration test sequence to validate end-to-end behavior.

Available tools

roku_deploy

Sideload an application onto the Roku device.

roku_screenshot

Capture a screenshot from the device and return it as a base64 image.

roku_device_info

Query device information including model, resolution, and firmware.

roku_check_resolution

Validate compatibility for HD and FHD display modes.

roku_keypress

Send a single remote control key press to the device.

roku_keypress_sequence

Send a sequence of key presses to automate navigation.

roku_input

Transmit custom events or deep link parameters.

roku_apps

List installed apps on the Roku device.

roku_active_app

Identify the currently running app on the device.

roku_launch

Launch or restart a specific app on the device.

roku_deep_link

Test and verify deep linking for apps.

roku_registry

Read app registry data from the device.

roku_app_state

Track the lifecycle and state of apps during tests.

roku_log

Collect BrightScript console logs in real time.

roku_sg_nodes

Inspect SceneGraph node trees for debugging.

roku_perf

Monitor CPU and memory usage of the device.

roku_graphics_fps

Measure graphics FPS to assess rendering performance.

roku_element

Find UI elements using WebDriver automation.

roku_focused_element

Identify the currently focused UI element.

roku_media_player

Monitor media playback state and events.

roku_server_check

Perform a health check on the MCP server.

roku_check_drm

Verify DRM protection status for content.

roku_check_accessibility

Check accessibility compliance of UI and content.

roku_check_raf

Validate RAF advertising framework integration.

roku_run_test

Execute an integrated test sequence.