DroidRun MCP Server

A text-based MCP (Model Context Protocol) server for controlling Android devices from Claude Code. Pure accessibility tree automation - no screenshots needed.

Features

Text-based UI interaction - Read and interact with Android UI elements using accessibility tree
No screenshots required - Faster and more efficient than vision-based approaches
Simple indexed tapping - Elements are numbered for easy interaction
Full device control - Navigate, type, swipe, and launch apps

Prerequisites

Android device with USB debugging enabled
Python 3.10+
ADB (Android Debug Bridge) installed on your computer
Claude Code CLI installed

Step 1: Install ADB

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install adb

macOS

brew install android-platform-tools

Windows

Download from Android SDK Platform Tools and add to PATH.

Step 2: Enable USB Debugging on Android

Go to Settings > About Phone
Tap Build Number 7 times to enable Developer Options
Go back to Settings > System > Developer Options
Enable USB Debugging
Connect your device via USB
Accept the "Allow USB debugging" prompt on your phone

Verify connection:

adb devices

You should see your device listed.

Step 3: Install DroidRun

pip install droidrun

Install DroidRun Portal App on Device

Run the setup command to install the Portal app on your Android device:

droidrun setup

This will:

Download the DroidRun Portal APK
Install it on your connected device
Open the Accessibility Settings

Enable Accessibility Service

After droidrun setup, you need to manually enable the accessibility service:

The Accessibility Settings will open automatically
Find DroidRun Portal in the list
Tap on it and enable the service
Confirm any permission dialogs

You can verify the setup worked:

droidrun test

Step 4: Install This MCP Server

Clone the repository

git clone https://github.com/chukfinley/droidrun-mcp-server.git
cd droidrun-mcp-server

Install dependencies

pip install droidrun mcp

Step 5: Configure Claude Code

Add the MCP server to your Claude Code configuration.

Edit ~/.claude.json and add under mcpServers:

{
  "mcpServers": {
    "droidrun": {
      "type": "stdio",
      "command": "python3",
      "args": ["/full/path/to/droidrun-mcp-server/server.py"],
      "env": {}
    }
  }
}

Important: Use the full absolute path to server.py!

Example:

{
  "mcpServers": {
    "droidrun": {
      "type": "stdio",
      "command": "python3",
      "args": ["/home/youruser/droidrun-mcp-server/server.py"],
      "env": {}
    }
  }
}

Restart Claude Code

claude

Available Tools

Tool	Description
`device_info()`	Get device model, Android version, and serial
`ui()`	Get current screen UI elements as indexed list
`tap(index)`	Tap element by index number from `ui()` output
`tap_xy(x, y)`	Tap screen at specific coordinates
`swipe(direction)`	Swipe up/down/left/right
`text(content)`	Input text (optionally tap element first)
`back()`	Press Android back button
`home()`	Press Android home button
`enter()`	Press Enter key
`app(package)`	Open app by package name
`apps()`	List installed apps (non-system)

Usage Example

Once configured, you can ask Claude Code to control your Android device:

> Open the Settings app and go to About Phone

Claude will:
1. Call app("com.android.settings")
2. Call ui() to see the screen
3. Call tap() on the appropriate elements
4. Navigate to About Phone

Example ui() output:

APP: Settings (com.android.settings)
KEYBOARD: hidden
FOCUS: none

1. TextView: "Network & internet" - (0,200,1080,300)
2. TextView: "Connected devices" - (0,300,1080,400)
3. TextView: "Apps" - (0,400,1080,500)
4. TextView: "About phone" - (0,900,1080,1000)

Then Claude taps element 4: tap(4)

How It Works

This MCP server wraps the DroidRun library to provide Android device control through Claude Code. It uses the Android accessibility tree (not screenshots) for UI detection, making it fast and reliable.

The DroidRun Portal app runs on your Android device and provides:

Accessibility service for UI tree extraction
Numbered overlay for visual feedback (optional)
Input method for text entry

Troubleshooting

"No Android device connected"

# Check if device is connected
adb devices

# If not listed, try:
adb kill-server
adb start-server
adb devices

"Portal is not installed"

droidrun setup

"Accessibility service not enabled"

Go to Settings > Accessibility
Find DroidRun Portal
Enable the service

Or run droidrun setup again - it will open the settings for you.

MCP server not showing in Claude Code

Check your ~/.claude.json configuration
Ensure the path to server.py is absolute (starts with /)
Restart Claude Code completely after config changes

"Permission denied" errors

Make sure server.py is executable:

chmod +x server.py

Quick Start Summary

# 1. Install ADB
sudo apt install adb  # Linux

# 2. Enable USB debugging on your Android device

# 3. Connect device and verify
adb devices

# 4. Install DroidRun
pip install droidrun

# 5. Setup Portal app on device
droidrun setup

# 6. Enable accessibility service on device (manual step!)

# 7. Clone this repo
git clone https://github.com/chukfinley/droidrun-mcp-server.git

# 8. Install dependencies
pip install droidrun mcp

# 9. Add to ~/.claude.json (see Step 5 above)

# 10. Restart Claude Code
claude

License

MIT

Credits

DroidRun - Android automation framework
MCP - Model Context Protocol by Anthropic

droidrun-mcp-server