# adb-tv-mcp

An MCP server that lets an AI agent control an Android TV or Android device through ADB.

## Overview

adb-tv-mcp is a local server for the [Model Context Protocol](https://modelcontextprotocol.io). The server gives an AI agent a set of tools. The agent uses the tools to control an Android device. The device must be reachable through the Android Debug Bridge (ADB).

The agent can do these tasks:

- Capture the screen as an image.
- Send remote-control and D-pad key presses.
- Start, install, and remove applications.
- Open a web address.
- Type text and touch the screen.
- Transfer files.
- Read device properties, settings, and logs.
- Run shell commands.
- Pair with a device that uses Android 11 wireless debugging.

The server sends each request to the `adb` program. The server does not modify the device firmware.

## Demo

Figure 1 shows a status display that the server sent to a TCL C6K television with the `adb_open_url` tool. The page runs in the television browser.

![A status display shown on a TCL C6K television](docs/jarvis-demo.gif)

## Features

- **Screen capture.** The `adb_screenshot` tool returns the screen as a PNG image. Vision-capable agents can see the screen and then act.
- **Remote control.** The tools send D-pad keys, media keys, and system keys, and also touch and text input.
- **Application control.** The tools start, list, install, and remove applications, and open web addresses.
- **Wireless pairing.** The `adb_pair` tool completes the Android 11 pairing sequence.
- **File transfer.** The tools copy files to and from the device.
- **Diagnostics.** The tools read properties, settings, and logs, and record the screen.

## Requirements

- Node.js version 18 or later.
- The Android platform-tools package. This package supplies the `adb` program.
- An Android device with developer options and debugging turned on.

## Installation

1. Clone the repository:

   ```bash
   git clone https://github.com/mosesmrima/adb-tv-mcp.git
   cd adb-tv-mcp
   ```

2. Install the dependencies:

   ```bash
   npm install
   ```

3. Build the project:

   ```bash
   npm run build
   ```

## Configuration

Add the server to the configuration file of your MCP client.

To use the published package, run it with `npx`. You do not need to clone the repository.

```json
{
  "mcpServers": {
    "adb-tv": {
      "command": "npx",
      "args": ["-y", "adb-tv-mcp"],
      "env": { "ADB_PATH": "/path/to/platform-tools/adb" }
    }
  }
}
```

To use a local build instead, set the command to `node` and give the absolute path to the built file:

```json
{
  "mcpServers": {
    "adb-tv": {
      "command": "node",
      "args": ["/absolute/path/to/adb-tv-mcp/dist/index.js"],
      "env": { "ADB_PATH": "/path/to/platform-tools/adb" }
    }
  }
}
```

Set the `ADB_PATH` variable only if the `adb` program is not on the `PATH` of the client process. Restart the client after you change the configuration.

## Connect to a device

### Android 11 or later (wireless debugging)

1. On the device, open **Developer options**.
2. Select **Wireless debugging**.
3. Select **Pair device with pairing code**. The device shows a 6-digit code and an address in the form `host:port`.
4. Tell the agent to run `adb_pair` with the host, the port, and the code.
5. Tell the agent to run `adb_connect` with the host and the connect port. The device shows the connect port on the main Wireless debugging screen.

Note: The pairing port and the connect port are different. The command `adb mdns services` also finds these endpoints.

### USB or earlier Android

1. Turn on network ADB on the device.
2. Tell the agent to run `adb_connect` with the device address and port 5555.

## Tools

| Tool | Description |
|---|---|
| `adb_devices` | Lists the connected devices and their state. |
| `adb_pair` | Pairs with a device that uses Android 11 wireless debugging. |
| `adb_connect` | Connects to a device endpoint. |
| `adb_disconnect` | Disconnects a device, or all devices. |
| `adb_screenshot` | Captures the screen and returns a PNG image. |
| `adb_screenrecord` | Records the screen and saves the video to a local file. |
| `adb_key` | Sends a remote-control or D-pad key. |
| `adb_tap` | Touches the screen at a pixel position. |
| `adb_swipe` | Swipes from one position to another. |
| `adb_text` | Types text into the active field. |
| `adb_launch` | Starts an application by package name. |
| `adb_open_url` | Opens a web address on the device. |
| `adb_start_intent` | Sends an Android intent with `am start`. |
| `adb_list_apps` | Lists installed packages. |
| `adb_current_app` | Reports the application in the foreground. |
| `adb_install` | Installs an APK file. |
| `adb_uninstall` | Removes an application. |
| `adb_push` | Copies a file to the device. |
| `adb_pull` | Copies a file from the device. |
| `adb_getprop` | Reads device properties. |
| `adb_settings` | Reads or writes an Android setting. |
| `adb_logcat` | Reads recent log lines. |
| `adb_reboot` | Restarts the device. |
| `adb_shell` | Runs a shell command. |

For the `adb_key` tool, use one of these key names, or a numeric Android key code:
`UP`, `DOWN`, `LEFT`, `RIGHT`, `ENTER`, `BACK`, `HOME`, `MENU`, `POWER`, `VOLUME_UP`, `VOLUME_DOWN`, `MUTE`, `PLAY_PAUSE`, `NEXT`, `PREV`, `FAST_FORWARD`, `REWIND`, `SEARCH`, `ASSIST`, `SETTINGS`, `APP_SWITCH`, `CHANNEL_UP`, `CHANNEL_DOWN`.

## Environment variables

| Variable | Description |
|---|---|
| `ADB_PATH` | The path to the `adb` program. The default value is `adb` on the `PATH`. |

## Security

Read this section before you use the server.

- The server controls real hardware.
- The `adb_shell` tool runs any shell command. The `adb_reboot` and `adb_uninstall` tools also make changes to the device.
- Use the server only with devices that you own or that you have permission to control.
- Do not connect the server to devices on a network that you do not trust.
- Give the agent only the autonomy that the task needs.

To report a security problem, see [SECURITY.md](./SECURITY.md).

## How it works

The server calls the `adb` command-line program with `execFile`. Each MCP tool is a wrapper around one `adb` operation. The server exposes the tools over the stdio transport of the MCP SDK.

The `adb_screenshot` tool reads the output of `screencap -p` and returns it as an MCP image block. An agent that supports images can see the screen and then choose the next action.

## Development

```bash
npm run dev     # run from source with tsx
npm run build   # compile TypeScript to dist/
npm start       # run the compiled server
```

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for the contribution process and the coding standards.

## License

This project uses the MIT License. See [LICENSE](./LICENSE).