@codmir/mobile-connector

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

• Ask the AI to list connected devices: "What Android devices are connected?"
• Take a screenshot to see the current screen: "Take a screenshot of my phone"
• Tap on a UI element: "Tap on the Settings icon at coordinates (540, 1200)"
• Launch an app: "Open Chrome on the phone"
• Type a URL: "Type https://codmir.com in the address bar"
• 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