Skip to content

Fastmcp #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nim444 merged 6 commits into from
Nov 21, 2025
Merged

Fastmcp #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
97500d9
Add initial implementation of Android Device Operator server using Fa…
nim444 Nov 21, 2025
b81ebc4
Refactor MCP
nim444 Nov 21, 2025
4d9c0c3
Refactor tool descriptions and formatting across multiple modules
nim444 Nov 21, 2025
8ece165
Enhance README with detailed server transport modes for AI agent and …
nim444 Nov 21, 2025
c460db6
Fix dependency installation command in CI workflow to use correct gro…
nim444 Nov 21, 2025
a1a622b
Create virtual environment in CI workflow before installing dependencies
nim444 Nov 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,14 @@ jobs:
- name: Add uv to PATH
run: echo "$HOME/.cargo/bin" >> $GITHUB_PATH

- name: Create virtual environment
run: uv venv

- name: Install dependencies (including dev)
run: uv pip install --system .
run: uv pip install --group dev .

- name: Lint with Ruff
run: uv run ruff check server.py
run: uv run ruff check server.py tools/


test:
Expand All @@ -54,9 +57,11 @@ jobs:
- name: Add uv to PATH
run: echo "$HOME/.cargo/bin" >> $GITHUB_PATH

- name: Create virtual environment
run: uv venv

- name: Install dependencies (including test)
run: uv pip install --system .
run: uv pip install --group dev .

- name: Run tests with pytest
run: uv run pytest -v
20 changes: 10 additions & 10 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,19 @@ description = "An MCP server for Android automation using UIAutomator2"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
"asyncio>=3.4.3",
"mcp[cli]>=1.7.0",
"uiautodev>=0.6.0", # This likely pins fastapi, which pins starlette < 0.38.0
"uiautomator2>=3.2.9",
"python-multipart>=0.0.9", # Already added
# "starlette>=0.38.0", # This caused conflicts, so we revert this change
"ruff>=0.11.8",
"pytest>=8.3.5",
"pytest-cov>=6.1.1",
"pytest-asyncio>=0.26.0",
"fastmcp==2.13.0",
"uiautodev>=0.13.4",
"uiautomator2>=3.5.0",
]

[tool.pytest.ini_options]
filterwarnings = [
"ignore:Please use \\`import python_multipart\\` instead.:PendingDeprecationWarning:starlette\\.formparsers",
]

[dependency-groups]
dev = [
"ruff>=0.14.4",
"pytest>=8.0.0",
"pytest-asyncio>=0.23.0",
]
223 changes: 179 additions & 44 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,33 @@

This project provides an **MCP (Model Context Protocol)** server for automating Android devices using [uiautomator2](https://github.com/openatx/uiautomator2). It's designed to be easily plugged into AI agents like GitHub Copilot Chat, Claude, or Open Interpreter to control Android devices through natural language.

## Modular Architecture

The server has been refactored into a clean, modular architecture with tools organized by functionality:

```
mcp-android-server-python/
├── server.py # Main server (61 lines - clean & focused)
├── server_original_backup.py # Backup of original monolithic version
└── tools/ # 🆕 Modular tools package
├── __init__.py # Central registration & imports
├── device_tools.py # Device connection & status tools
├── app_tools.py # Application management tools
├── screen_tools.py # Screen control & unlock tools
├── input_tools.py # User input simulation (click, swipe, text)
├── inspection_tools.py # UI inspection & screenshots
└── advanced_tools.py # Advanced features (toast, activity wait)
```

### Benefits of Modular Architecture

- **Maintainability**: Easy to add/modify/remove tools without touching main server
- **Organization**: Tools grouped logically by functionality
- **Testing**: Individual tool modules can be unit tested separately
- **Reusability**: Tool modules can be reused in other projects
- **Scalability**: New tool categories can be added as separate modules
- **Clean Code**: Main server reduced from 1321 lines to 61 lines

## Quick Demo

![Demo](.docs/demo.gif)
Expand All @@ -22,14 +49,40 @@ This project provides an **MCP (Model Context Protocol)** server for automating

## Features

- Start, stop, and manage apps by package name
- Retrieve installed apps and current foreground app
- Tap, swipe, scroll, drag, and perform UI interactions
- Get device info, screen resolution, battery status, and more
- Capture screenshots or last toast messages
- Programmatically unlock, wake, or sleep the screen
- Clear app data and wait for activities
- Includes a health check and `adb` diagnostic tool
### Device Management
- **Smart Device Detection**: Automatically finds and connects to available devices
- **Comprehensive Device Info**: Get serial, resolution, battery, WiFi IP, Android version
- **ADB Diagnostics**: Check ADB availability and connection status
- **Health Monitoring**: Built-in server health checks

### Application Management
- **App Discovery**: List all installed applications (system + user apps)
- **App Lifecycle Control**: Start, stop, force-stop apps by package name
- **App State Monitoring**: Track current foreground app and activity
- **Data Management**: Clear app data/cache for testing

### Screen & Display Control
- **Screen Power Management**: Turn screen on/off programmatically
- **Smart Unlock**: Automatic screen unlocking with standard methods
- **Screen State Monitoring**: Wait for screen activation (async support)

### User Input Simulation
- **Precision Interactions**: Click by text, resource ID, or content description
- **Advanced Gestures**: Long click, swipe, drag operations
- **Text Input**: Smart text entry with optional field clearing
- **Hardware Keys**: Simulate home, back, menu, volume keys

### UI Inspection & Debugging
- **Element Analysis**: Get detailed UI element properties and bounds
- **Screen Capture**: Take screenshots for debugging and documentation
- **UI Hierarchy**: Export complete screen structure as XML
- **Smart Waiting**: Wait for elements to appear with custom timeouts
- **Scroll Detection**: Auto-scroll to find elements in long lists

### Advanced Capabilities
- **Toast Detection**: Capture system toast messages for verification
- **Activity Monitoring**: Wait for specific Android activities
- **Background Operations**: Async support for time-consuming operations

## Use Cases

Expand Down Expand Up @@ -67,21 +120,63 @@ uv pip install

## Running the Server

### Option 1: Using uvicorn (Recommended)
The server supports two different transport modes depending on your use case:

### Option 1: MCP stdio (For AI Agent Integration)

This is the standard mode for integrating with AI agents like Claude Desktop, VS Code, or other MCP clients.

```bash
uvicorn server:app --factory --host 0.0.0.0 --port 8000
# Edit server.py to use stdio mode (default commented out)
# Uncomment the stdio section and comment out http section

# Then run:
uv run python server.py
```

### Option 2: Using MCP stdio (For AI agent integration)
### Option 2: Streamable HTTP (For Web/API Integration)

This mode runs the server as an HTTP API, useful for web applications, curl testing, or direct HTTP calls.

```bash
python server.py
# Current default configuration - runs as HTTP server
uv run python server.py

# Server will be available at: http://localhost:8080
```

### Switching Between Modes

Edit `server.py` and modify the `if __name__ == "__main__":` section:

**For stdio mode (AI agents):**
```python
if __name__ == "__main__":
mcp.run(
transport="stdio",
show_banner=False,
)
```

**For HTTP mode (Web API):**
```python
if __name__ == "__main__":
mcp.run(
transport="streamable-http",
host="0.0.0.0",
port=8080,
)
```

## Usage

An MCP client is needed to use this server. The Claude Desktop app is an example of an MCP client. To use this server with Claude Desktop:
### For AI Agent Integration (Claude Desktop, VS Code, etc.)

An MCP client is needed to use this server. The Claude Desktop app is an example of an MCP client.

**Important:** For AI agent integration, make sure to configure the server in **stdio mode** (see "Option 1" above).

To use this server with Claude Desktop:

### Locate your Claude Desktop configuration file

Expand All @@ -98,7 +193,7 @@ An MCP client is needed to use this server. The Claude Desktop app is an example
"command": "bash",
"args": [
"-c",
"cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"
"cd /path/to/mcp-adb && source .venv/bin/activate && uv run python server.py"
]
}
}
Expand All @@ -121,7 +216,7 @@ You can also use this MCP server with VS Code's agent mode (requires VS Code 1.9
"command": "bash",
"args": [
"-c",
"cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"
"cd /path/to/mcp-adb && source .venv/bin/activate && uv run python server.py"
]
}
}
Expand All @@ -138,6 +233,24 @@ After adding the configuration, you can manage the server using:

![Vscode](.docs/mcp-vscode.png)

### For HTTP API Integration (Direct API Calls)

When running in HTTP mode (Option 2), you can interact with the server directly via HTTP requests:

```bash
# Check if server is running
curl http://localhost:8080/

# List available tools (you'll need to implement proper tool discovery endpoints)
# This depends on your FastMCP version and configuration
```

**Use Cases for HTTP Mode:**
- Web applications with Android automation
- Testing tools that can't use stdio
- Direct API integration with other services
- Debugging and development with curl/Postman

## UI Inspector

The project includes support for uiauto.dev, a powerful UI inspection tool for viewing and analyzing your device's interface structure.
Expand All @@ -160,35 +273,57 @@ uiauto.dev

## Available MCP Tools

| Tool Name | Description |
|-----------------------|--------------------------------------------------------------------------|
| `mcp_health` | Check if the MCP server is running properly |
| `connect_device` | Connect to an Android device and get basic info |
| `get_installed_apps` | List all installed apps with version and package info |
| `get_current_app` | Get info about the app currently in the foreground |
| `start_app` | Start an app by its package name |
| `stop_app` | Stop an app by its package name |
| `stop_all_apps` | Stop all currently running apps |
| `screen_on` | Turn on the screen |
| `screen_off` | Turn off the screen |
| `get_device_info` | Get detailed device info: serial, resolution, battery, etc. |
| `press_key` | Simulate hardware key press (e.g. `home`, `back`, `menu`, etc.) |
| `unlock_screen` | Unlock the screen (turn on and swipe if necessary) |
| `check_adb` | Check if ADB is installed and list connected devices |
| `wait_for_screen_on` | Wait asynchronously until the screen is turned on |
| `click` | Tap on an element by `text`, `resourceId`, or `description` |
| `long_click` | Perform a long click on an element |
| `send_text` | Input text into currently focused field (optionally clearing before) |
| `get_element_info` | Get info on UI elements (text, bounds, clickable, etc.) |
| `swipe` | Swipe from one coordinate to another |
| `wait_for_element` | Wait for an element to appear on screen |
| `screenshot` | Take and save a screenshot from the device |
| `scroll_to` | Scroll until a given element becomes visible |
| `drag` | Drag an element to a specific screen location |
| `get_toast` | Get the last toast message shown on screen |
| `clear_app_data` | Clear user data/cache of a specified app |
| `wait_activity` | Wait until a specific activity appears |
| `dump_hierarchy` | Dump the UI hierarchy of the current screen as XML |
### Device Management Tools
| Tool Name | Description |
|-----------|-------------|
| `mcp_health` | Check if the MCP server is running properly |
| `get_device_status` | Get complete device status and readiness information |
| `connect_device` | Connect to an Android device and get basic info |
| `get_device_info` | Get detailed device info: serial, resolution, battery, etc. |
| `check_adb_and_list_devices` | Check if ADB is installed and list connected devices |

### Application Management Tools
| Tool Name | Description |
|-----------|-------------|
| `get_installed_apps` | List all installed apps with version and package info |
| `get_current_app` | Get info about the app currently in the foreground |
| `start_app` | Start an app by its package name |
| `stop_app` | Stop an app by its package name |
| `stop_all_apps` | Stop all currently running apps |
| `clear_app_data` | Clear user data/cache of a specified app |

### Screen Control Tools
| Tool Name | Description |
|-----------|-------------|
| `screen_on` | Turn on the screen |
| `screen_off` | Turn off the screen |
| `unlock_screen` | Unlock the screen (turn on and swipe if necessary) |
| `wait_for_screen_on` | Wait asynchronously until the screen is turned on |

### User Input Tools
| Tool Name | Description |
|-----------|-------------|
| `press_key` | Simulate hardware key press (e.g. `home`, `back`, `menu`, etc.) |
| `click` | Tap on an element by `text`, `resourceId`, or `description` |
| `long_click` | Perform a long click on an element |
| `send_text` | Input text into currently focused field (optionally clearing before) |
| `swipe` | Swipe from one coordinate to another |
| `drag` | Drag an element to a specific screen location |

### Inspection Tools
| Tool Name | Description |
|-----------|-------------|
| `get_element_info` | Get info on UI elements (text, bounds, clickable, etc.) |
| `wait_for_element` | Wait for an element to appear on screen |
| `scroll_to` | Scroll until a given element becomes visible |
| `screenshot` | Take and save a screenshot from the device |
| `dump_hierarchy` | Dump the UI hierarchy of the current screen as XML |

### Advanced Tools
| Tool Name | Description |
|-----------|-------------|
| `get_toast` | Get the last toast message shown on screen |
| `wait_activity` | Wait until a specific activity appears |

---

Expand Down
Loading