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. 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.

Related MCP server: Android MCP Server

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.

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:

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

2. Install the dependencies:

   npm install

3. Build the project:

   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.

{
  "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:

{
  "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

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

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.

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

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 for the contribution process and the coding standards.

License

This project uses the MIT License. See LICENSE.