What is Androidtvmcp

AndroidTVMCP is a Model Context Protocol (MCP) server designed to provide Android TV remote control functionalities. It serves as a bridge between Android TV devices and AI-assisted technologies, facilitating automation and workflow integration through standard protocols.

Use cases

AndroidTVMCP can be employed in various scenarios, including controlling media playback, navigating the Android TV interface, managing applications, and monitoring device status through AI assistants. This functionality is suitable for home automation, smart home environments, and enhancing user experience by allowing voice commands and remote control capabilities.

How to use

To use AndroidTVMCP, start by installing the package and creating a virtual environment if desired. Launch the MCP server with specific host and port configurations. Afterward, connect your MCP client, such as an AI assistant, to the server to issue remote control commands, like navigating, launching apps, or querying the device’s current state.

Key features

Key features of AndroidTVMCP include automatic device discovery, complete remote control capabilities (navigation and playback), app management functions, real-time state monitoring, and compliance with the Model Context Protocol for easy integration with various clients.

Where to use

AndroidTVMCP is ideal for use in smart homes, media centers, and any environment where voice-activated control of Android TV devices is desired. It can be integrated into AI platforms or custom applications requiring media playback control and device management over a local network.

AndroidTVMCP - Android TV Remote Control to MCP Bridge

A Model Context Protocol (MCP) server that provides Android TV remote control functionality to AI assistants and other MCP clients.

Overview

AndroidTVMCP bridges Android TV remote control capabilities with the Model Context Protocol, enabling seamless integration of Android TV control into AI-powered workflows and automation systems.

Features

• Device Discovery: Automatic detection of Android TV devices on the local network
• Remote Control: Full navigation and playback control capabilities
• App Management: Launch and switch between Android TV applications
• State Monitoring: Query device status and current state
• MCP Integration: Standard MCP protocol compliance for easy integration

Quick Start

Installation

Using Virtual Environment (Recommended)

# Create a virtual environment
python -m venv androidtvmcp-env

# Activate the virtual environment
# On Linux/macOS:
source androidtvmcp-env/bin/activate
# On Windows:
# androidtvmcp-env\Scripts\activate

# Install the package
pip install androidtvmcp

Global Installation

pip install androidtvmcp

Basic Usage

1. Start the MCP server:

androidtvmcp --host localhost --port 8080

2. Configure your MCP client to connect to the server

3. Use Android TV control tools through your AI assistant

Example Commands

• Navigate: “Move up on the Android TV”
• Playback: “Pause the current video”
• Apps: “Launch Netflix on Android TV”
• Status: “What’s currently playing on Android TV?”

Configuration

Create a configuration file config.json:

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

MCP Tools

Navigation Tools

• atv_navigate: Navigate Android TV interface (up, down, left, right, select, menu, back, home)
• atv_input_text: Send text input to Android TV

Playback Tools

• atv_playback: Control media playback (play, pause, stop, fast_forward, rewind)
• atv_volume: Adjust volume (up, down, mute)

App Management Tools

• atv_launch_app: Launch specific applications
• atv_get_apps: List available applications
• atv_switch_app: Switch between running applications

Device Tools

• atv_get_devices: List discovered Android TV devices
• atv_get_status: Get current device status and state
• atv_power: Power control (on, off, sleep)

MCP Resources

Device Information

• device://[device_id]/info: Device capabilities and information
• device://[device_id]/status: Current device status
• device://[device_id]/apps: Available applications

Current State

• state://current_app: Currently active application
• state://playback: Current playback status
• state://volume: Current volume level

Development

Setup Development Environment

Using Virtual Environment (Recommended)

# Clone the repository
git clone https://github.com/pigeek/androidtvmcp.git
cd androidtvmcp

# Create and activate virtual environment
python -m venv venv

# Activate the virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows:
# venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Alternative Setup

git clone https://github.com/pigeek/androidtvmcp.git
cd androidtvmcp
pip install -e ".[dev]"

Run Tests

pytest

Development Tools

The devtools/ directory contains standalone scripts for manual testing and validation:

cd devtools
python test_command_processor.py  # Test command processor functionality
python test_mcp_client.py         # Test MCP client-server communication
python test_mcp_integration.py    # Test MCP server integration

See devtools/README.md for detailed information about each script.

Code Formatting

black src/ tests/
isort src/ tests/

Type Checking

mypy src/

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │◄──►│  AndroidTVMCP   │◄──►│   Android TV    │
│  (AI Assistant) │    │    Server       │    │   Devices       │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Components

• MCP Server: Handles MCP protocol communication
• Device Manager: Manages Android TV device discovery and connections
• Command Processor: Translates MCP requests to Android TV commands
• Network Layer: Handles Android TV protocol communication

Requirements

• Python 3.8+
• Android TV devices on the same network
• Network connectivity for device discovery

Troubleshooting

Common Issues

1. Device Not Found

   • Ensure Android TV is on the same network
   • Check firewall settings
   • Verify device discovery is enabled

2. Connection Failed

   • Check network connectivity
   • Verify Android TV remote control is enabled
   • Try restarting the Android TV device

3. Commands Not Working

   • Ensure device is powered on
   • Check if device supports the command
   • Verify connection status

Debug Mode

Enable debug logging:

androidtvmcp --log-level DEBUG

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• GitHub Issues
• Documentation
• MCP Protocol Documentation

Related Projects

• androidtvremote2 - Android TV remote control library
• Model Context Protocol - Protocol specification