MCP ecp

Description

Execute External Control Protocol (ECP) commands against a Roku device. Supports:

• query/app-ui: Inspect the active app's UI tree
• query/device-info: Retrieve device information (model, serial number, software version, etc.)
• keypress: Simulate pressing a remote control key
• keysequence: Simulate a sequence of remote control key presses
• input: Send custom launch parameters to the running app

Defaults to JSON output for AI consumption, with an opt-in XML response when the raw ECP payload is needed.

Hint for AI assistants:

• Prefer calling this MCP tool directly instead of running external scripts.
• Use command="keypress" only for a single button press.
• Use command="keysequence" for 2+ button presses or any navigation flow.
• If a user asks to "run a sequence", "navigate", or press multiple keys in order, choose keysequence.

Examples:

• Single press: { "command": "keypress", "key": "Home" }
• Sequence: { "command": "keysequence", "keys": ["Home", "Home"] }
• Sequence with delay: { "command": "keysequence", "keys": ["Down", "Down", "Select"], "delay": 300 }

Required parameters:

• command (string): ECP command to execute ("query/app-ui", "query/device-info", "keypress", "keysequence", "input"; "query-ui" is deprecated alias for query/app-ui)
• key (string): Required for keypress command. Remote control key name (e.g., "Home", "Select", "Up", "Down", "Lit_a")
• keys (array): Required for keysequence command. Ordered list of keys as strings and/or objects { key, delay? }
• params (object) or uri (string): Required for input command. Either params object with key-value pairs or uri string with pre-encoded query string.

Optional parameters:

• delay (number): Default delay in ms for keysequence command (applied after each key, before next; default 100)
• format (string): "json" (default) or "xml" response format (not applicable for keypress, keysequence, or input)
• host (string): Direct target host/IP (bypasses device store selection for target resolution).
• password (string): Device password override (applies to host mode and can override stored device password).
• device (string): Device identifier (ID, IP, or exact name). Uses active device when omitted.

Supported keypress keys:

• Standard: Home, Rev, Fwd, Play, Select, Left, Right, Down, Up, Back, InstantReplay, Info, Backspace, Search, Enter
• TV: VolumeDown, VolumeMute, VolumeUp, PowerOff, PowerOn, ChannelUp, ChannelDown, InputTuner, InputHDMI1-4, InputAV1
• Special: FindRemote
• Text: Lit_<char> for on-screen keyboard (e.g., Lit_a, Lit_5)

See also

• HTTP sendEcpCommand (POST /api/ecp)
• rk ecp query/app-ui
• rk ecp query/device-info
• rk ecp keypress
• rk ecp input
• rk keysequence

Parameters

additionalProperties: false

command

ECP command to execute. Use keypress for single key, keysequence for multi-key sequences/navigation.

key

Key name for keypress command (single press only). Required when command is 'keypress'.

keys

Ordered keys for keysequence command (preferred for 2+ presses). Each item can be a string key or an object { key, delay? } where delay is applied after that key.

keys fields

delay

Default delay in milliseconds for keysequence. Must be > 0. Per-key delay in object form overrides this value for that step.

params

Input parameters as key-value pairs for input command. Use either params or uri, not both.

params fields

uri

Pre-encoded URI query string for input command (e.g., 'contentId=123&mediaType=movie'). Use either params or uri, not both.

format

Response format: json (default) or xml. Not applicable for keypress or input.

host

Direct target host/IP (bypasses device store selection for target resolution)

password

Device password override (applies to host mode and can override stored device password)

device

Target device (ID, IP, exact name, or rce:<name>). Uses active device when omitted.