Androidtvmcp

🚀 AndroidTVMCP - Android TV Remote Control to MCP Bridge

A Model Context Protocol (MCP) server that enables AI assistants and other MCP clients to control Android TVs.

🚀 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?"

✨ Features

• 🔍 Device Discovery: Automatically detect Android TV devices on the local network
• 🎮 Remote Control: Provide 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: Comply with the standard MCP protocol for easy integration

📚 Documentation

⚙️ 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

🔧 Technical Details

🛠️ 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