MCP 服务器

AndroidTVMCP

A Model Context Protocol server that enables AI assistants to control Android TV devices, providing remote control functionality like navigation, playback control, app management, and device status monitoring.

README

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

Start the MCP server:

androidtvmcp --host localhost --port 8080

Configure your MCP client to connect to the server
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

Device Not Found
- Ensure Android TV is on the same network
- Check firewall settings
- Verify device discovery is enabled
Connection Failed
- Check network connectivity
- Verify Android TV remote control is enabled
- Try restarting the Android TV device
Commands Not Working
- Ensure device is powered on
- Check if device supports the command
- Verify connection status