Roku MCP

A standalone Model Context Protocol (MCP) server for Roku development. Create projects, look up BrightScript APIs, validate and package channels, run script tests, and capture headless SceneGraph or Draw2D previews.

Uses stdio transport. Requires Node.js 22 or newer and a working native canvas installation. No build step is needed to start the server.

Install

git clone https://github.com/vynxc/roku-mcp.git
cd roku-mcp
npm ci

canvas may need native build prerequisites if a prebuilt binary is unavailable for your platform. Run roku_doctor after connecting to check the runtime and PNG encoder.

Connect an MCP client

Add this entry to your client's MCP configuration, replacing both absolute paths:

{
  "mcpServers": {
    "roku": {
      "command": "node",
      "args": [
        "/absolute/path/to/roku-mcp/scripts/mcp.mjs",
        "--workspace",
        "/absolute/path/to/your/roku-projects"
      ]
    }
  }
}

The workspace directory must already exist. The server also accepts ROKU_WORKSPACE; otherwise it uses its working directory. Relative tool paths resolve inside that workspace. Absolute paths must also stay inside it. Diagnostics go to stderr; stdout is reserved for MCP messages.

Tools

Start with roku_doctor, create or inspect a project, edit its sources with your client's file tools, then check, build, test, and preview. Each result includes ok; failed calls also set MCP isError. Preview reports include local artifact paths for PNGs and JSON logs.

Example tool arguments:

{"action":"create","project":"my-channel","template":"scenegraph","title":"My Channel"}

{"project":"my-channel","steps":[{"key":"up","wait_ms":100},{"key":"select","wait_ms":100}],"duration_ms":500,"output":"preview-001"}

{"files":["tests/main.brs"],"expect_logs":["TEST_PASS"],"timeout_ms":10000}

Project creation and explicit output paths must be new. Default outputs use unique directories under .roku-artifacts. Preview steps, execution time, logs, archive sizes, and file counts are bounded. Cancellation and connection closure terminate active tool subprocesses.

Limits

This is a simulator, not Roku OS. Hardware validation is still required for playback, DRM, performance, signing, and certification. No physical device discovery, deployment, or control is exposed. Reference data is bundled with BrighterScript and may differ from the current Roku SDK.

Run trusted apps only. Subprocesses inherit the server's OS permissions and environment; simulator apps may make network requests. Workspace path checks and symlink rejection are not an OS sandbox. Configure isolation in your MCP host or operating system when needed. Custom build hooks and file mappings are not executed.

Development

npm ci
npm test
npm run check:roku

Tests build sample ZIPs under dist/, exercise the MCP stdio connection, and cover project validation, packaging, runtime failures, remote input, and PNG output. Runtime implementation lives in src/headless; scripts/roku.mjs is the internal subprocess worker.

MIT licensed. Derived from dsh-roku-dev; original copyright is retained in LICENSE. Uses BrighterScript and the BrightScript simulator; dependencies retain their respective licenses. Not affiliated with Roku.