# 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](https://www.justwatch.com/) 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.

## What can it do?

- **"Play Stranger Things"** — finds it on Netflix, launches with deep link, selects your profile
- **"Play Frozen on Disney+"** — opens directly to the movie
- **"Play Bohemian Rhapsody"** — finds the song on Spotify, plays it, queues similar music
- **"What services have The Boys?"** — shows it's on Prime Video, Apple TV, etc.
- **"Pause"** / **"Next episode"** / **"Rewind"** — remote control commands
- **"Turn off the TV"** / **"Turn on the TV"** — power control with Wake-on-LAN
- **"Volume up"** / **"Mute"** — volume control
- **"Open YouTube"** — launches any installed app
- **"Play The Boys on the Bob profile"** — picks a specific streaming profile

## 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)

## Enable ADB on your TV

Before anything else, you need to enable ADB (Android Debug Bridge) on your TV. This is a one-time setup:

1. Go to **Settings** > **Device Preferences** > **About**
2. Tap **Build number** 7 times — you'll see "You are now a developer"
3. Go back — **Developer options** now 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** and check "Always allow from this computer"

> The exact menu path may vary by manufacturer. On some TVs it's Settings > About > Build number. Search "[your TV brand] enable developer options" if the above doesn't match.

## Prerequisites

- **Node.js 18+**
- **ADB** installed on your machine:
  - macOS: `brew install android-platform-tools`
  - Ubuntu/Debian: `sudo apt install adb`
  - Windows: [Download platform-tools](https://developer.android.com/tools/releases/platform-tools)
- **Spotify Developer App** (optional — only needed for music search)

## Installation

```bash
npm install -g remote-control-tv
```

### Setup

```bash
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

<details>
<summary><strong>Claude Code</strong></summary>

Add to `~/.claude/settings.json`:

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

Or without global install:

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

</details>

<details>
<summary><strong>VS Code / Cursor</strong></summary>

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

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

</details>

<details>
<summary><strong>Any MCP-compatible client</strong></summary>

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

</details>

## 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) |

### 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` |

## Profile setup

Streaming apps like Netflix, Disney+, and Prime Video show a "Who's watching?" profile picker. Run the profile wizard to configure them:

```bash
remote-control-tv profiles
```

The wizard detects which apps are installed, auto-reads Disney+ profiles directly from the TV, and walks you through Netflix and Prime Video interactively. No manual config editing needed.

## Spotify setup (optional)

For music search, create a free Spotify Developer App:

1. Go to [developer.spotify.com/dashboard](https://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 in config. Pass the `tv` parameter in tool calls to select which one. If omitted, uses `defaultTv` or the first TV in the list.

## 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](https://modelcontextprotocol.io/docs/tools/inspector):

```bash
npx @modelcontextprotocol/inspector remote-control-tv
```

Check ADB connectivity:

```bash
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