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

1. Go to Settings > About Phone
2. Tap Build Number 7 times to enable Developer Options
3. Go back to Settings > System > Developer Options
4. Enable USB Debugging
5. Connect your device via USB
6. 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:

1. Download the DroidRun Portal APK
2. Install it on your connected device
3. Open the Accessibility Settings

Enable Accessibility Service

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

1. The Accessibility Settings will open automatically
2. Find DroidRun Portal in the list
3. Tap on it and enable the service
4. 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"

1. Go to Settings > Accessibility
2. Find DroidRun Portal
3. Enable the service

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

MCP server not showing in Claude Code

1. Check your ~/.claude.json configuration
2. Ensure the path to server.py is absolute (starts with /)
3. 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