Androidtvmcp

You can bridge Android TV remote control capabilities with the Model Context Protocol (MCP) so your AI assistants and automation tools can discover, control, and monitor Android TV devices from a unified interface. This MCP server provides device discovery, navigation and playback control, app management, and status queries, all exposed through MCP so you can build automation flows and assistive agents around Android TV.

How to use

Start the MCP server locally and connect your MCP client to it. The server exposes commands that let you navigate the Android TV interface, control playback, launch apps, and query device status. Once the client is connected, you can issue actions such as moving the focus on the screen, sending text input, launching a specific app, or retrieving information about the currently active app and playback state.

How to install

Prerequisites: you need Python 3.8+ installed on your system and Android TV devices on the same network.

# Optional: create and activate a virtual environment
python -m venv androidtvmcp-env
# On Linux/macOS:
source androidtvmcp-env/bin/activate
# On Windows:
androidtvmcp-env\Scripts\activate

# Install the MCP server package
pip install androidtvmcp

Basic run command to start the MCP server locally on port 8080.

androidtvmcp --host localhost --port 8080

Configuration

You can configure discovery, timeouts, MCP connection details, and logging via a JSON configuration file named config.json. Here is an example structure you can adapt to your environment.

{
  "devices": {
    "discovery": {
      "enabled": true,
      "timeout": 10
    },
    "connection": {
      "timeout": 5,
      "retry_attempts": 3
    }
  },
  "mcp": {
    "host": "localhost",
    "port": 8080,
    "transport": "stdio"
  },
  "logging": {
    "level": "INFO",
    "file": "androidtvmcp.log"
  }
}

Troubleshooting

If you encounter issues, verify that the Android TV devices are on the same network and that device discovery is enabled. Ensure the target Android TV supports the commands you’re sending and that the MCP client is connected to the correct host and port. If commands are not performing as expected, check the device power state and restart the Android TV device if necessary.

Enable debug logging to get more details about MCP communication and device interactions.

androidtvmcp --log-level DEBUG

MCP endpoints and tools

This server exposes a set of MCP endpoints to discover devices, query status, and issue control commands. Key tool families include navigation, playback, app management, and device information. You can invoke these tools from your MCP client to perform actions on the Android TV.

Navigation and input: navigate the interface, enter text, and move focus.

Playback and volume: control play/pause, stop, rewind/fast-forward, and adjust volume.

Apps and devices: launch apps, list available apps, switch between running apps, and query device status.

Code examples and structure

# Example: start server (stdin/stdout MCP)
androidtvmcp --host localhost --port 8080

# Example: configuration snippet (config.json)
{
  "devices": { /*...*/ },
  "mcp": { "host": "localhost", "port": 8080, "transport": "stdio" }
}

Development and testing

If you are developing or testing locally, you can install in development mode and run unit or integration tests. Use a virtual environment to isolate dependencies.

# Development setup
git clone https://github.com/pigeek/androidtvmcp.git
cd androidtvmcp
python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
pip install -e ".[dev]"

pytest

Architecture

The MCP server comprises a Server component that implements MCP protocol handling, a Device Manager that discovers Android TV devices, a Command Processor that translates MCP requests into Android TV actions, and a Network Layer that handles communication with TV devices.

Available tools

atv_navigate

Navigate the Android TV interface using directional inputs (up, down, left, right, select, menu, back, home) to reach menus and options.

atv_input_text

Send text input to the Android TV to search or type in apps and fields.

atv_playback

Control media playback including play, pause, stop, fast_forward, and rewind.

atv_volume

Adjust the system volume or mute output on the Android TV.

atv_launch_app

Launch a specified application on the Android TV.

atv_get_apps

List the applications installed on the Android TV.

atv_switch_app

Switch focus between currently running applications.

atv_get_devices

Discover Android TV devices on the local network.

atv_get_status

Retrieve the current status and state of the Android TV device.

atv_power

Power control for the Android TV (on, off, sleep).