Android Remote Control MCP

An Android application that runs as an MCP (Model Context Protocol) server, enabling AI models to fully control an Android device remotely using accessibility services and screenshot capture.

The app runs directly on your Android device (or emulator) and exposes an HTTP server (with optional HTTPS) implementing the MCP protocol. AI models like Claude can connect to it and interact with any app on the device — reading UI elements, tapping buttons, typing text, swiping, capturing screenshots, managing files, launching apps, and more.

⚠️ Disclaimer: This software is provided "as-is" without warranty of any kind, for research and educational purposes only. The authors do not condone the use of this tool for any illegal, unauthorized, or unethical activities. Users are solely responsible for ensuring their use complies with all applicable laws and regulations. By using this software, you agree to use it responsibly and at your own risk.

Features

MCP Server

• HTTP server running directly on Android (Ktor + Netty), with optional HTTPS
• Streamable HTTP transport at /mcp (MCP specification compliant, JSON-only, no SSE)
• Bearer token authentication (global, all requests)
• Auto-generated self-signed TLS certificates (or custom certificate upload)
• Configurable binding: localhost (127.0.0.1) or network (0.0.0.0)
• Auto-start on boot
• Remote access tunnels via Cloudflare Quick Tunnels or ngrok (public HTTPS URL)

54 MCP Tools across 12 Categories

All tool names use the android_ prefix by default (e.g., android_tap). When a device slug is configured (e.g., pixel7), the prefix becomes android_pixel7_ (e.g., android_pixel7_tap). See docs/MCP_TOOLS.md for the full naming convention.

See docs/MCP_TOOLS.md for full tool documentation with input/output schemas and examples.

Android App

• Material Design 3 UI with tabbed layout (Server / Settings / About) and dark mode
• Server status monitoring (running/stopped) with permission warning banner
• Connection info display (IP, port, token, tunnel URL)
• Per-tool and per-parameter permissions (enable/disable individual MCP tools)
• Permission management (Accessibility, Notifications, Camera, Microphone)
• Remote access tunnel configuration (Cloudflare / ngrok)
• Storage location management (SAF authorization for file tools)
• Server log viewer (MCP tool calls, tunnel events)
• Headless setup via ADB (configure, grant permissions, start/stop server without UI)

Comparison with Alternatives

Most alternatives rely on ADB running on a host machine, which means a USB cable or local network connection and a computer sitting next to the phone. This project runs entirely on the device itself, so you can expose the MCP endpoint through a tunnel and control your phone from anywhere.

On the token efficiency side, ADB-based tools typically return raw uiautomator XML dumps which can easily be 10-50x more verbose than the compact representation used here. Combined with numbered screenshot annotations, configurable image quality, and the ability to disable tools you don't need (every tool definition costs tokens on every turn), this significantly reduces the per-interaction cost in agentic loops.

Requirements

For Building

• JDK 17 (e.g., Eclipse Temurin)
• Android SDK with API 34 (Android 14)
• Gradle 8.x (wrapper included, no global install needed)

For Running

• Android device or emulator running Android 13+ (API 33+), targeting Android 14 (API 34)
• adb (Android Debug Bridge) for device/emulator management

For E2E Tests

• Podman (rootful, for redroid/redroid Android container image)

Check all dependencies:

make check-deps

Quick Start

1. Build the App

git clone https://github.com/danielealbano/android-remote-control-mcp.git
cd android-remote-control-mcp
make build

2. Install on Device/Emulator

# Start an emulator (if no device connected)
make setup-emulator
make start-emulator

# Install the debug APK
make install

3. Configure Permissions

1. Enable Accessibility Service: Open the app, tap "Enable Accessibility Service", and toggle it on in Android Settings. This also enables screenshot capture via the takeScreenshot() API (Android 11+).
2. Grant Camera & Microphone (optional, for camera tools): Grant via the app UI or make grant-permissions.

4. Start the MCP Server

Tap the "Start Server" button in the app. The server starts on http://127.0.0.1:8080 by default (HTTPS is disabled by default).

5. Connect from Host Machine

Set up port forwarding (if server is bound to localhost):

make forward-port

Test the connection:

curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

6. Make MCP Tool Calls

All requests are sent as JSON-RPC 2.0 via POST /mcp (Streamable HTTP transport):

# List available tools
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Get the current screen state (UI nodes + optional screenshot)
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"android_get_screen_state","arguments":{}}}'

# Tap at coordinates
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"android_tap","arguments":{"x":540,"y":1200}}}'

The bearer token is displayed in the app's connection info section. You can copy it directly from the app.

Building

Debug Build

make build
# APK: app/build/outputs/apk/debug/app-debug.apk

Release Build

make build-release
# APK: app/build/outputs/apk/release/app-release.apk

For signed release builds, create keystore.properties in the project root:

storeFile=path/to/your.keystore
storePassword=your_store_password
keyAlias=your_key_alias
keyPassword=your_key_password

Clean Build

make clean

Testing

Unit Tests

make test-unit

Runs JUnit 5 unit tests with MockK for mocking. Tests cover accessibility tree parsing, node finding, screenshot encoding, settings repository, network utilities, and all 54 MCP tool handlers.

Integration Tests

make test-integration

Runs JVM-based integration tests using Ktor testApplication (no device or emulator required). Tests the full HTTP stack: authentication, JSON-RPC protocol, tool dispatch for all 12 tool categories, and error handling.

Note: Some integration tests (e.g., NgrokTunnelIntegrationTest) require environment variables. Copy .env.example to .env and fill in the required values. The Makefile sources .env automatically.

E2E Tests

make test-e2e

Requires rootful Podman. Starts a redroid Android container via Podman, installs the app, and performs real MCP tool calls. Includes:

• Calculator test: 7 + 3 = 10 via MCP tools (verifies full stack)
• Screenshot test: Capture with different quality settings
• Error handling test: Authentication, unknown tools, invalid params

All Tests

make test

Code Coverage

make coverage

Generates a Jacoco HTML report at app/build/reports/jacoco/jacocoTestReport/html/index.html. Minimum coverage target: 80%.

Architecture

The application is a service-based Android app with three main components:

1. McpAccessibilityService - UI introspection, action execution, and screenshot capture via Android Accessibility APIs (takeScreenshot() on Android 11+)
2. McpServerService - Foreground service running the Ktor HTTP/HTTPS server
3. MainActivity - Jetpack Compose UI for configuration and control

graph TB
    Client["MCP Client (AI Model)"]
    Client -->|"HTTP/HTTPS POST /mcp + Bearer Token"| McpServer

    subgraph Device["Android Device"]
        subgraph McpServerService["McpServerService (Foreground Service)"]
            McpServer["McpServer (Ktor)"]
            McpServer -->|"Streamable HTTP /mcp"| SDK["SDK Server (MCP Kotlin SDK)"]
            SDK -->|"54 MCP Tools"| Tools["Tool Handlers"]
            TunnelMgr["TunnelManager (optional)"]
            TunnelMgr -->|"Cloudflare / ngrok"| PublicURL["Public HTTPS URL"]
        end

        subgraph Accessibility["McpAccessibilityService"]
            TreeParser["AccessibilityTreeParser"]
            ElemFinder["ElementFinder"]
            ActionExec["ActionExecutor"]
            ScreenEnc["ScreenshotEncoder"]
        end

        subgraph Storage["Storage & App Services"]
            StorageProv["StorageLocationProvider"]
            FileOps["FileOperationProvider"]
            AppMgr["AppManager"]
        end

        subgraph CameraSvc["Camera Services"]
            CamProv["CameraProvider\n(CameraX)"]
        end

        subgraph IntentSvc["Intent Services"]
            IntentDisp["IntentDispatcher"]
        end

        subgraph NotifSvc["Notification Services"]
            NotifProv["NotificationProvider"]
            NotifListener["McpNotificationListenerService"]
        end

        MainActivity["MainActivity (Compose UI)"]

        Tools --> Accessibility
        Tools --> Storage
        Tools --> CameraSvc
        Tools --> IntentSvc
        Tools --> NotifSvc
        MainActivity -->|"StateFlow (status)"| McpServerService
    end

See docs/ARCHITECTURE.md for detailed architecture documentation.

Configuration

Server Settings (via App UI)

Headless Setup via ADB

The app can be fully configured and controlled from the command line without opening the UI. This is useful for automated setups, CI pipelines, or headless devices.

Replace <app-id> with the application ID for your build:

• Debug: com.danielealbano.androidremotecontrolmcp.debug
• Release: com.danielealbano.androidremotecontrolmcp

Grant Permissions

# Enable Accessibility Service (required for UI introspection, actions, and screenshots)
adb shell settings put secure enabled_accessibility_services \
  <app-id>/com.danielealbano.androidremotecontrolmcp.services.accessibility.McpAccessibilityService

# Grant notification permission (Android 13+)
adb shell pm grant <app-id> android.permission.POST_NOTIFICATIONS

# Grant camera permission
adb shell pm grant <app-id> android.permission.CAMERA

# Grant microphone permission
adb shell pm grant <app-id> android.permission.RECORD_AUDIO

Configure the App

All extras are optional — only the ones provided are updated. The app does not need to be open.

adb shell am broadcast \
  -a com.danielealbano.androidremotecontrolmcp.ADB_CONFIGURE \
  -n <app-id>/com.danielealbano.androidremotecontrolmcp.services.mcp.AdbConfigReceiver \
  --es bearer_token "my-secret-token" \
  --es binding_address "0.0.0.0" \
  --ei port 8080 \
  --ez auto_start_on_boot true \
  --ez https_enabled false \
  --es certificate_source "AUTO_GENERATED" \
  --es certificate_hostname "mcp.local" \
  --ez tunnel_enabled false \
  --es tunnel_provider "CLOUDFLARE" \
  --es ngrok_authtoken "your-ngrok-token" \
  --es ngrok_domain "your-domain.ngrok-free.app" \
  --ei file_size_limit_mb 50 \
  --ez allow_http_downloads false \
  --ez allow_unverified_https_certs false \
  --ei download_timeout_seconds 60 \
  --es device_slug "pixel8" \
  --es tool_permissions '{"disabled_tools":["tap"],"disabled_params":{"swipe":["duration_ms"]}}'

Start the MCP Server

The server must be started via a trampoline Activity (required on Android 12+ to gain foreground service exemption). This works even when the app is force-stopped.

adb shell am start \
  -n <app-id>/com.danielealbano.androidremotecontrolmcp.services.mcp.AdbServiceTrampolineActivity \
  --es action start

Stop the MCP Server

adb shell am start \
  -n <app-id>/com.danielealbano.androidremotecontrolmcp.services.mcp.AdbServiceTrampolineActivity \
  --es action stop

Using with adb Port Forwarding (Recommended)

When the server is bound to 127.0.0.1 (default, most secure):

# Forward device port to host
adb forward tcp:8080 tcp:8080

# Test connection from host
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

Using over Network

When the server is bound to 0.0.0.0:

1. Find the device's IP address (shown in the app's connection info)
2. Connect directly via POST http://DEVICE_IP:8080/mcp with bearer token

Warning: Binding to 0.0.0.0 exposes the server to all devices on the same network. Only use on trusted private networks.

Using Remote Access Tunnels

For connecting from outside the local network without port forwarding:

1. Cloudflare Quick Tunnels (default, no account required): Creates a temporary tunnel with a random *.trycloudflare.com HTTPS URL.
2. ngrok (account required): Supports optional custom domains. Requires an ngrok authtoken (free tier available). Only available on ARM64 devices.

Enable the tunnel in the app's "Remote Access" section. The public URL is displayed in the connection info and server logs.

Security

HTTPS (Optional, Disabled by Default)

• HTTPS can be enabled in the app settings for encrypted TLS communication
• When enabled, uses auto-generated self-signed certificates (or upload your own CA-signed certificate)
• Certificate is stored in app-private storage
• Server defaults to HTTP; enable HTTPS when operating on untrusted networks

Bearer Token Authentication

• Every MCP request requires Authorization: Bearer <token> header
• Token is auto-generated on first launch (UUID)
• Token can be viewed, copied, and regenerated in the app
• Constant-time comparison prevents timing attacks

Binding Address

• Default 127.0.0.1: Only accessible via adb port forwarding (most secure)
• Optional 0.0.0.0: Accessible over network (use only on trusted networks)
• Security warning dialog displayed when switching to network mode

Permissions

• Accessibility Service: Required for UI introspection, actions, and screenshots (user must enable manually)
• Camera: Required for camera photo/video tools (runtime permission, system dialog)
• Record Audio: Required for video recording with audio (runtime permission, system dialog)
• Internet: For running the HTTP/HTTPS server
• Foreground Service: For keeping services alive in background
• Receive Boot Completed: For auto-start on boot
• Query All Packages: For listing installed applications (android_list_apps)
• Kill Background Processes: For closing background applications (android_close_app)
• Notification Listener: Required for notification tools (user must enable manually in Settings > Notifications > Notification access)
• Storage Access Framework: Per-location authorization via system file picker (for file tools)
• No root access required

Linting

# Check for issues
make lint

# Auto-fix issues
make lint-fix

Uses ktlint for code style and detekt for static analysis.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Make your changes following the project conventions (see docs/PROJECT.md)
4. Ensure all checks pass: make lint && make test-unit && make build
5. Commit with descriptive messages (e.g., feat: add new MCP tool for ...)
6. Open a pull request

Development Conventions

• Language: Kotlin with Android (Jetpack Compose, Ktor)
• Architecture: Service-based with SOLID principles
• Testing: JUnit 5 + MockK (unit), Ktor testApplication (JVM integration), Testcontainers (E2E)
• Linting: ktlint + detekt
• DI: Hilt (Dagger-based)

See docs/PROJECT.md for the complete project bible.

License

This project is licensed under the MIT License. See LICENSE.md for details.