RokuMCP

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

Plugin mode (Claude Code and Cursor)

Unofficial community tool. Not affiliated with or endorsed by Roku, Inc.

The repo also ships as a plugin: the MCP server, workflow skills (skills/), and Cursor rules, registered together.

• Claude Code: /plugin marketplace add jack1590/RokuMCP then /plugin install roku-mcp@roku-mcp-marketplace. Manifests: .claude-plugin/, .mcp.json.
• Cursor: manifests in .cursor-plugin/ and mcp.json. Skills in skills/, rules in rules/cursor/.

Claude Code asks for the device host and developer password when the plugin is enabled (the password is stored as sensitive). Both clients use the entry point bootstrap.mjs. Both run npm ci and npm run build on first start (Node 18+). Outside plugin mode, ROKU_DEVICE_HOST / ROKU_DEVICE_PASSWORD or a project .env still work.

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

Cursor — agent-mode tools, auto-discovers MCP servers

Prerequisites: Cursor 0.45+ with Agent mode.

Install: create .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{

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

Then reload the window (Cmd+Shift+P / Ctrl+Shift+P → Developer: Reload Window).

Verify: open Cursor Settings → MCP and confirm the roku row shows a green dot. If it appears disabled, click the toggle. In a new agent chat, type list roku tools — you should see roku_deploy, roku_screenshot, etc.

Routing rule (recommended): the repo also ships an AGENTS.md. Cursor picks it up automatically, so the agent knows the canonical *observe → act → wait → verify* loop and the RTA uiElementId gotcha without you having to re-explain it every session.

Troubleshoot: if the server stays grey/disabled, check View → Output → MCP Logs — the most common cause is ROKU_DEVICE_HOST unreachable on the LAN. Omit the env block entirely to fall back to SSDP auto-discovery.

VS Code (GitHub Copilot) — agent mode, MCP via .vscode/mcp.json

Prerequisites: VS Code 1.99+ with the GitHub Copilot extension and an active Copilot subscription that includes Agent mode.

Install: 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" } } } }

Reload the window (Cmd+Shift+P / Ctrl+Shift+P → Developer: Reload Window).

Verify: open Copilot Chat, switch the chat-mode dropdown to Agent, and ask "what roku tools do you have?". You should see the full roku_* list. The MCP panel (Cmd+Shift+P → MCP: List Servers) should show roku as Running.

Troubleshoot: if the server fails to start, run npx -y roku-mcp --help in a regular terminal first — that confirms Node 18+ and npx are working before VS Code launches it.

Claude Desktop — official Anthropic desktop app

Prerequisites: Claude Desktop (latest from claude.ai/download), Node.js 18+ on PATH.

Install: edit your Claude Desktop config:

• 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" } } } }

Fully quit and restart Claude Desktop (the menu-bar icon must close — Cmd+Q on macOS).

Verify: open a new chat. The 🛠️ icon in the input bar should list roku-mcp with all its tools. Ask "take a Roku screenshot" — Claude will request approval for roku_screenshot and run it.

Troubleshoot: if no tool icon appears, check ~/Library/Logs/Claude/mcp-server-roku.log (macOS) — command not found: npx means Node isn't on the GUI app's PATH. Either install Node via the official .pkg, or hard-code the absolute paths: "command": "/usr/local/bin/node", "args": ["/usr/local/bin/npx", "-y", "roku-mcp"].

Windsurf — Codeium's agentic IDE

Prerequisites: Windsurf with Cascade enabled.

Install: create .windsurf/mcp.json in your project root (or ~/.codeium/windsurf/mcp_config.json globally):

{

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

Reload the window. In Cascade settings, refresh the MCP server list.

Verify: ask Cascade "list available MCP tools" — roku_* entries should appear.

Troubleshoot: Windsurf occasionally caches a stale server. If reloads don't pick up edits, fully quit Windsurf and reopen.

Any MCP-compatible client (Continue, Cline, Zed, Codex, Claude Code, OpenCode, …)

The server speaks the standard MCP stdio transport. Anywhere you can declare:

command: npx

args: ["-y", "roku-mcp"] env: { ROKU_DEVICE_HOST: "...", ROKU_DEVICE_PASSWORD: "..." }

…the server runs. Both env vars are optional: omit ROKU_DEVICE_HOST to use SSDP auto-discovery on the LAN, and pass host / password on each tool call to override.

The repo-root AGENTS.md is picked up automatically by Claude Code, OpenCode, Codex CLI, and any other tool that follows the AGENTS.md convention, so those agents inherit the same usage guidance without extra setup.

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](#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

| `roku_c