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.

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

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.

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.