Content
# 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)
```bash
# 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
```bash
pip install androidtvmcp
```
### Basic Usage
1. Start the MCP server:
```bash
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`:
```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)
```bash
# 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
```bash
git clone https://github.com/pigeek/androidtvmcp.git
cd androidtvmcp
pip install -e ".[dev]"
```
### Run Tests
```bash
pytest
```
### Development Tools
The `devtools/` directory contains standalone scripts for manual testing and validation:
```bash
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
```bash
black src/ tests/
isort src/ tests/
```
### Type Checking
```bash
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:
```bash
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](LICENSE) file for details.
## Support
- [GitHub Issues](https://github.com/pigeek/androidtvmcp/issues)
- [Documentation](https://androidtvmcp.readthedocs.io/)
- [MCP Protocol Documentation](https://modelcontextprotocol.io/)
## Related Projects
- [androidtvremote2](https://github.com/tronikos/androidtvremote2) - Android TV remote control library
- [Model Context Protocol](https://modelcontextprotocol.io/) - Protocol specification
