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

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

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