mcp-android-server-python: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP Android Agent is an MCP (Model Context Protocol) server for automating Android devices using uiautomator2. It exposes Android device control functionality through MCP tools that can be consumed by AI agents like Claude Desktop, GitHub Copilot Chat, or VS Code agent mode.

Requirements: Python 3.10+ (tested on 3.10, 3.11, 3.12, 3.13)

Development Commands

Environment Setup

Quick Install (Automated):

# Run the installation script (handles everything)
./install.sh

Manual Install:

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies (using uv - preferred)
uv pip install -e .

# Or using traditional pip
pip install -r requirements.txt

ADB Configuration

If ADB is not in your system PATH:

1. Copy the environment template:

cp .env.example .env

1. Edit .env and configure your Android SDK path:

# Recommended: Set ANDROID_HOME
ANDROID_HOME=/Users/username/Library/Android/sdk

# Alternative: Set direct ADB path
# ADB_PATH=/Users/username/Library/Android/sdk/platform-tools/adb

The server checks for ADB in this order:

1. ADB_PATH environment variable (direct path)
2. ANDROID_HOME/platform-tools/adb
3. System PATH

Running the Server

Quick Start:

# MCP stdio mode (for Claude Desktop, VS Code)
./start.sh

# HTTP mode (for development/testing)
./start-http.sh

Manual Start:

# Activate virtual environment first
source .venv/bin/activate

# MCP stdio mode (for AI agent integration)
python3 server.py

# HTTP mode with uvicorn (for development/testing)
uvicorn server:app --factory --host 0.0.0.0 --port 8000

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov

# Run specific test file
pytest tests/test_server.py

Code Quality

# Lint and format with ruff
ruff check .
ruff format .