AI agents meet
your Roku.
MCP server and CLI that lets AI agents interact with Roku devices. Inspect SceneGraph UI, send remote input, take screenshots, run smoke tests, cert preflight — all through natural language.
npx -y --package @danecodes/roku-mcp roku-mcp-server Works with your agent
Talk to your Roku
through your agent.
Your coding agent uses MCP tools to navigate, inspect, and screenshot the device. No new API to learn — just describe what you want in natural language.
You: Go to the browse screen, select the Action
genre, and take a screenshot for me.
Agent: I'll navigate to the Browse screen.
→ roku_press_key(key: "Back")
→ roku_press_key(key: "Left")
→ roku_ui_tree(depth: 4)
Agent: I can see the nav menu. Let me find
Browse and select it.
→ roku_press_key(key: "Down", times: 2)
→ roku_press_key(key: "Select")
→ roku_press_key(key: "Down", times: 4)
→ roku_press_key(key: "Select")
Agent: We're on the Action genre list now.
→ roku_screenshot(save_path: "./action.png")Everything your agent needs to work with a Roku.
Inspect the UI
Query the full SceneGraph node tree to see what's on screen. CSS-like selectors: HomePage HomeHeroCarousel, AppButton#play_button.
Send Input
Remote control keys, D-pad navigation, text entry. Press, hold, repeat — all through natural language.
Screenshots
Capture the current screen and save to disk. Visual proof for QA, bug reports, or CI artifacts.
Smoke Tests
Launch, verify UI renders, check playback starts. Full pass/fail report with step-by-step detail.
Cert Preflight
Run Roku certification failure checklist — back nav, Home exit, relaunch, error scan — before you submit.
Performance Sampling
Sample CPU via chanperf during playback. Get high watermark and pass/fail against your threshold.
Console Logs
Read BrightScript debug output — errors, print statements, crashes. Watch for patterns during a time window.
Sideload & Watch
Deploy a .zip to the device and monitor console for errors. CI-ready pass/fail report.
Agent Efficiency
Token-efficient tools: focused_element, screen_name, console_watch. Get just what the agent needs.
You: Sideload the build and run a smoke test.
Deep link to content "ABC123XYZ" (episode)
and verify playback starts.
Agent: Sideloading and watching console...
→ roku_sideload_and_watch(
zip_path: "./target/build.zip",
duration: 30000)
{ "passed": true,
"message": "PASS: Install Success —
no errors in 30s of console output" }
Agent: Clean install. Running smoke test.
→ roku_smoke_test(
content_id: "ABC123XYZ",
media_type: "episode",
playback_timeout: 30000)
{ "passed": true,
"steps": [
{ "name": "launch", "passed": true },
{ "name": "ui_visible", "passed": true,
"elapsed_ms": 2340 },
{ "name": "playback", "passed": true,
"elapsed_ms": 8710 }
] }Smoke tests in one prompt.
Sideload a dev build, watch the console for crashes, then run a full smoke test with playback verification. Your agent reports back with pass/fail and timing.
All test tools return structured JSON — CI-friendly exit codes included for the CLI.
26 tools across 4 categories.
Device Control
roku_ui_tree Get the full SceneGraph UI tree
roku_find_element Find elements by CSS-like selector
roku_press_key Send remote control key press
roku_type_text Type text into keyboard inputs
roku_screenshot Take a screenshot, save to disk
roku_launch Launch a channel with deep link params
roku_deep_link Deep link into content by ID
roku_close_app Close the running app
roku_sideload Deploy a .zip package to the device
roku_device_info Get device model, software, network
roku_active_app Get the currently running app
roku_media_player Get playback state and position
roku_installed_apps List all installed channels
roku_console_log Read BrightScript debug console
roku_console_command Send debug commands (bt, var, etc.)
roku_volume Volume up, down, or mute
roku_input Send custom input params to the app
Test Runner
roku_wait_for Poll until a selector appears on screen
roku_assert_element Assert element exists, focused, or has attribute
roku_sideload_and_watch Sideload + watch console for errors
roku_smoke_test Launch, verify UI, verify playback
Agent Efficiency
roku_focused_element Currently focused element (token-efficient)
roku_screen_name Infer current screen from SceneGraph root
roku_console_watch Monitor console for pattern match
Shift Left Quality Gates
roku_cert_preflight Roku cert failure checklist
roku_chanperf_sample CPU sampling via chanperf
How it works
Roku devices expose an HTTP API called ECP (External Control Protocol) on port 8060. roku-mcp calls ECP endpoints directly — no WebDriver, no Appium, no Selenium, no Java.
Let your agent see the screen.
Set up in two minutes. Works with any Roku device in developer mode.