remote-control-tv

An MCP server that lets AI agents control Android TVs — search for content across streaming services and play it, manage power and volume, send remote control commands, all via ADB.

Say "play Stranger Things" and it finds it on Netflix, launches the deep link, navigates the profile picker, and starts playback. No manual searching, no menus, no remote.

How it works

1. You ask your AI agent to play something
2. The server searches JustWatch to find which streaming services have it and gets the Android TV deep link
3. It sends ADB commands to your TV: force-stops the app if needed, launches the deep link, detects the profile picker, and selects your profile
4. Content plays. Results are cached locally so repeat requests are instant.

For music, it searches the Spotify API to find the exact track and artist, then opens Spotify with a targeted search that plays the right song and auto-queues similar music.

Supported devices

Any device running Android TV or Google TV:

• TV brands: Philips, Sony, TCL, Hisense, Sharp, and others with Android TV
• Streaming devices: NVIDIA Shield, Xiaomi Mi Box, Chromecast with Google TV
• Amazon Fire TV (partial — ADB works, some deep link formats may differ)

Prerequisites

• Node.js 18+
• ADB (Android Debug Bridge) installed on your machine
• Developer Options + USB debugging enabled on the TV (how to enable)
• Spotify Developer App (optional — only needed for music search)

Installation

npm install -g remote-control-tv

Setup

remote-control-tv setup

The wizard connects to your TV, tests the connection, and saves configuration to ~/.remote-control-tv/config.json.

Add to your AI agent

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "tv": {
      "command": "remote-control-tv"
    }
  }
}

Or without global install:

{
  "mcpServers": {
    "tv": {
      "command": "npx",
      "args": ["-y", "remote-control-tv"]
    }
  }
}

Add to .vscode/mcp.json in your workspace or user settings:

{
  "servers": {
    "tv": {
      "command": "remote-control-tv"
    }
  }
}

The server uses stdio transport. Run remote-control-tv as a subprocess and communicate via JSON-RPC over stdin/stdout.

Tools

| Tool | Description | Key parameters | |------|-------------|----------------| | tv_play | Search for content and play it. Handles deep linking, app force-stops, and profile selection automatically. | title (required), service, profile, music | | tv_search | Search for content without playing. Returns available services and deep links. | title (required), type (video/music) | | tv_power | Power on, off, toggle, or check status. Supports Wake-on-LAN for TVs in deep standby. | action (required: on/off/toggle/status) | | tv_volume | Adjust volume up/down, mute/unmute, or set to a level. | action (required: up/down/mute/unmute/set), steps, level | | tv_key | Send any remote control key press. | key (required), count, delay | | tv_app | Launch an app by name. | app (required) |

Which tool should I use?

• "Play Stranger Things" → tv_play with title: "Stranger Things"
• "Play Bohemian Rhapsody on Spotify" → tv_play with title: "Bohemian Rhapsody", music: true
• "What services have Frozen?" → tv_search with title: "Frozen"
• "Pause" / "Next episode" → tv_key with key: "pause" / key: "next"
• "Turn off the TV" → tv_power with action: "off"
• "Volume up 5 steps" → tv_volume with action: "up", steps: 5
• "Open YouTube" → tv_app with app: "youtube"

Supported apps

youtube, netflix, disney, prime, spotify, jellyfin, hbo, skyshowtime, youtube_music, youtube_kids

Custom apps can be added via config.

Supported keys

| Category | Keys | |----------|------| | Navigation | up, down, left, right, center/ok, back, home, enter | | Playback | play, pause, play_pause, stop, next, previous, fast_forward, rewind | | Volume | volume_up, volume_down, mute | | Power | power, sleep, wakeup | | System | search, settings, tv_input |

Configuration

After running remote-control-tv setup, edit ~/.remote-control-tv/config.json to configure profiles and preferences.

Example config

{
  "tvs": [
    {
      "name": "living-room",
      "host": "192.168.1.100",
      "adbPort": 5555,
      "mac": "AA:BB:CC:DD:EE:FF",
      "profiles": {
        "netflix": {
          "names": ["Alice", "Bob", "Kids"],
          "default": "Alice",
          "layout": "vertical",
          "detection": "uidump"
        },
        "disney": {
          "names": ["Alice", "Bob"],
          "default": "Alice",
          "layout": "horizontal",
          "detection": "uidump"
        },
        "prime": {
          "names": ["Alice", "Bob", "Kids"],
          "default": "Alice",
          "layout": "vertical",
          "detection": "logcat"
        }
      }
    }
  ],
  "country": "US",
  "servicePriority": ["netflix", "disney", "prime", "hbo", "skyshowtime", "spotify"]
}

Config reference

| Field | Description | Default | |-------|-------------|---------| | tvs | Array of TV configurations | [] | | tvs[].name | Name to identify this TV | — | | tvs[].host | TV IP address | — | | tvs[].adbPort | ADB port | 5555 | | tvs[].mac | MAC address for Wake-on-LAN | — | | tvs[].profiles | Profile config per streaming service | {} | | tvs[].apps | Custom app overrides {name: {package, activity}} | — | | defaultTv | Name of TV to use when none specified | First TV | | country | ISO country code for content search | US | | servicePriority | Preferred service order when multiple available | netflix, disney, prime, hbo, skyshowtime, spotify | | spotify.clientId | Spotify Developer App client ID | — | | spotify.clientSecret | Spotify Developer App client secret | — |

Profile setup

Most streaming apps show a "Who's watching?" profile picker. Configure profiles so the server can navigate to the right one automatically.

| Field | Description | |-------|-------------| | names | Profile names in display order (top-to-bottom for vertical, left-to-right for horizontal) | | default | Profile to use when none is specified | | layout | vertical (Netflix, Prime Video) or horizontal (Disney+) | | detection | How to detect the picker: uidump (Netflix, Disney+), logcat (Prime Video), timeout (fallback) |

How detection works:

• uidump — Polls the Android UI hierarchy. For Netflix, checks whether the app jumped straight to playback (skipping profiles) or is showing the picker. For Disney+, looks for "Who's watching?" text.
• logcat — Monitors Android logs for profile picker events. Used for Prime Video which has a custom renderer that doesn't expose UI elements.
• timeout — Waits a fixed duration then navigates blindly. Fallback for untested apps.

Spotify setup (optional)

For music search, create a free Spotify Developer App:

1. Go to developer.spotify.com/dashboard
2. Create an app (redirect URI: https://localhost, select Web API)
3. Add clientId and clientSecret to your config

Without Spotify configured, tv_play with music: true will return an error. All other tools work without it.

Multiple TVs

Add multiple entries to the tvs array. Pass the tv parameter in tool calls to select which one. If omitted, uses defaultTv or the first TV in the list.

Enable ADB on your TV

1. Settings > Device Preferences > About
2. Tap Build number 7 times — you'll see "You are now a developer"
3. Go back — Developer options appears under Device Preferences
4. Enable USB debugging (some TVs call it "Network debugging")
5. Reboot the TV
6. When you first connect via ADB, the TV will show "Allow USB debugging?" — accept it

Known quirks

• Netflix ignores deep links when already running. The server force-stops it before each launch.
• Netflix sometimes skips the profile picker entirely. The server detects this and avoids sending unnecessary key presses that would interfere with playback.
• Spotify TV app only responds to spotify:search: URIs (not spotify:track: or spotify:artist:). The server works around this by using the Spotify API to identify the exact artist and track name, then constructs a precise search query.
• Prime Video uses a custom renderer. Profile detection uses logcat monitoring instead of UI inspection.
• Deep standby drops the TV off the network entirely. Configure the mac field for Wake-on-LAN, or enable "Network standby" in TV settings.

Debugging

Test your server with the MCP Inspector:

npx @modelcontextprotocol/inspector remote-control-tv

Check ADB connectivity:

adb connect <TV_IP>:5555
adb -s <TV_IP>:5555 shell echo ok

Contributing

Contributions welcome. Some areas that could use help:

• App-specific deep link testing — verify deep link formats on different TV brands and Android versions
• Profile detection — improve detection reliability for more streaming services (HBO Max, SkyShowtime, etc.)
• Fire TV support — test and document differences for Amazon Fire TV devices
• Additional streaming services — add app registry entries and deep link patterns

License

MIT