Ryan Malloy
db6998510c
- FastMCP server with STDIO interface - Comprehensive ADB tools for device automation - Docker support with USB device access - Console script entry point for uvx compatibility - Type-safe Pydantic models for all parameters Tools included: - adb_devices: List connected Android devices - adb_screenshot: Capture and retrieve screenshots - adb_input: Send taps, swipes, key events, text - adb_launch_app: Launch apps by package name - adb_launch_url: Open URLs in browser - adb_list_packages: List installed packages - adb_shell_command: Execute shell commands 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
133 lines
2.7 KiB
Markdown
133 lines
2.7 KiB
Markdown
# Android MCP Server
|
|
|
|
A Model Context Protocol (MCP) server for Android device automation via ADB. This server provides tools for interacting with Android devices through ADB commands in a structured, type-safe way.
|
|
|
|
## Features
|
|
|
|
- **Device Management**: List and interact with connected Android devices
|
|
- **Screenshots**: Capture and retrieve device screenshots
|
|
- **Input Simulation**: Send taps, swipes, key events, and text input
|
|
- **App Control**: Launch apps by package name or open URLs
|
|
- **Package Management**: List installed packages
|
|
- **Shell Commands**: Execute arbitrary shell commands on device
|
|
|
|
## Tools Available
|
|
|
|
### `adb_devices()`
|
|
List all connected Android devices with their IDs and status.
|
|
|
|
### `adb_screenshot(device_id?, local_filename?)`
|
|
Take a screenshot and save it locally.
|
|
|
|
### `adb_input(action, device_id?)`
|
|
Send input events:
|
|
- `tap`: Tap at coordinates (x, y)
|
|
- `swipe`: Swipe from (x, y) to (x2, y2)
|
|
- `key`: Send key event (key_code)
|
|
- `text`: Type text
|
|
|
|
### `adb_launch_app(package_name, device_id?)`
|
|
Launch an app by package name.
|
|
|
|
### `adb_launch_url(url, device_id?)`
|
|
Open URL in default browser.
|
|
|
|
### `adb_list_packages(device_id?, filter_text?)`
|
|
List installed packages, optionally filtered.
|
|
|
|
### `adb_shell_command(command, device_id?)`
|
|
Execute shell command on device.
|
|
|
|
## Usage
|
|
|
|
### Using uvx (Recommended)
|
|
```bash
|
|
# Run directly with uvx
|
|
uvx android-mcp-server
|
|
|
|
# Or from PyPI once published
|
|
uvx android-mcp-server
|
|
```
|
|
|
|
### Local Development
|
|
```bash
|
|
# Install dependencies
|
|
uv sync
|
|
|
|
# Run the server
|
|
uv run android-mcp-server
|
|
```
|
|
|
|
### Docker Development
|
|
```bash
|
|
# Build and run with Docker Compose
|
|
docker-compose up --build
|
|
|
|
# Or build manually
|
|
docker build -t android-mcp-server .
|
|
docker run --privileged -v /dev/bus/usb:/dev/bus/usb android-mcp-server
|
|
```
|
|
|
|
## MCP Client Configuration
|
|
|
|
### Using uvx (Recommended)
|
|
Add to your MCP client configuration:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"android-adb": {
|
|
"command": "uvx",
|
|
"args": ["android-mcp-server"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Local Development
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"android-adb": {
|
|
"command": "uv",
|
|
"args": ["run", "android-mcp-server"],
|
|
"cwd": "/path/to/android-mcp-server"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Docker
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"android-adb": {
|
|
"command": "docker",
|
|
"args": ["run", "--privileged", "-v", "/dev/bus/usb:/dev/bus/usb", "android-mcp-server"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Python 3.11+
|
|
- ADB (Android Debug Bridge)
|
|
- USB access to Android devices
|
|
- Device with USB debugging enabled
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install dev dependencies
|
|
uv sync --group dev
|
|
|
|
# Format code
|
|
uv run black src/
|
|
|
|
# Lint
|
|
uv run ruff check src/
|
|
|
|
# Type check
|
|
uv run mypy src/
|
|
``` |