Codmir Mobile Connector

An MCP (Model Context Protocol) server that gives AI assistants the ability to control Android phones via ADB and scrcpy. Connect Claude, Cursor, Windsurf, or any MCP-compatible AI to a physical Android device or emulator for UI testing, automation, screenshots, and app control.

Prerequisites

• ADB (Android Debug Bridge) installed and on PATH
  • macOS: brew install android-platform-tools
  • Linux: sudo apt install adb
  • Windows: Install via Android Studio or standalone platform-tools
• USB Debugging enabled on the target Android device
  • Go to Settings > About Phone > tap Build Number 7 times
  • Go to Settings > Developer Options > enable USB Debugging
• scrcpy (optional, for screen mirroring)
  • macOS: brew install scrcpy
  • Linux: sudo apt install scrcpy

Setup

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "codmir-mobile": {
      "command": "npx",
      "args": ["@codmir/mobile-connector"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "codmir-mobile": {
      "command": "npx",
      "args": ["@codmir/mobile-connector"]
    }
  }
}

Windsurf

Add to .windsurf/mcp.json in your project:

{
  "mcpServers": {
    "codmir-mobile": {
      "command": "npx",
      "args": ["@codmir/mobile-connector"]
    }
  }
}

Tools

| Tool | Description | |------|-------------| | mobile_list_devices | List all connected Android devices | | mobile_get_device_info | Get detailed device info (model, OS, battery, IP) | | mobile_screenshot | Take a screenshot, returns base64 PNG | | mobile_tap | Tap at screen coordinates | | mobile_swipe | Swipe gesture between two points | | mobile_type_text | Type text on the device | | mobile_press_key | Press a hardware/software key | | mobile_back | Press the back button | | mobile_home | Press the home button | | mobile_recents | Open recent apps | | mobile_wake | Wake the screen | | mobile_launch_app | Launch an app by package name | | mobile_stop_app | Force stop an app | | mobile_list_apps | List installed third-party apps | | mobile_install_app | Install an APK file | | mobile_shell | Run a shell command on the device | | mobile_open_url | Open a URL in the device browser | | mobile_push_file | Push a file to the device | | mobile_pull_file | Pull a file from the device | | mobile_screen_record | Record the device screen |

Example Usage Flow

1. Ask the AI to list connected devices: "What Android devices are connected?"
2. Take a screenshot to see the current screen: "Take a screenshot of my phone"
3. Tap on a UI element: "Tap on the Settings icon at coordinates (540, 1200)"
4. Launch an app: "Open Chrome on the phone"
5. Type a URL: "Type https://codmir.com in the address bar"
6. Swipe to scroll: "Scroll down on the page"

Multiple Devices

If multiple devices are connected, pass the serial parameter to target a specific device. Use mobile_list_devices to see all available serials.

Library Usage

You can also import the package programmatically:

import { listDevices, screenshot, tap, typeText } from '@codmir/mobile-connector';

const devices = await listDevices();
const base64 = await screenshot(devices[0].serial);
await tap(540, 1200, devices[0].serial);
await typeText('hello world', devices[0].serial);

License

Apache-2.0