phone

This MCP server provides a bridge to control an Android device via ADB commands using a Python-based MCP plugin. It exposes a suite of phone-related commands through the phone-mcp interface, including dialing, messaging, contact management, app launching, screen capture, UI interaction, and screen analysis. You can issue commands directly in your AI assistant conversation (for example, Claude) to perform actions on the connected device. Typical workflows include dialing a number, sending an SMS, launching apps or specific activities, taking screenshots, or interacting with UI elements through tap, swipe, text input, and wait/monitor commands. The plugin also supports advanced UI automation and screen analysis to enable robust automation even on devices with varying layouts.

To use it, ensure your environment has ADB installed and your Android device is connected with USB debugging enabled. The server runs as a Python/uvx process (as shown in the configuration) and listens for commands from your assistant integration. When you issue commands like phone-cli call <number> or phone-cli screenshot, the MCP translates them into ADB actions on the device and returns results or success/failure feedback to you.

Prerequisites:

• Python 3.7+ (or a suitable environment that provides uvx)
• ADB installed and available on PATH
• USB debugging enabled on the Android device and device connected

Installation options (choose one):

1. Quick start with uvx (recommended):

# If you have uvx installed (part of uv), run the MCP directly
uvx phone-mcp

2. Install with uv (Python package manager):

uv pip install phone-mcp

3. Install with pip directly:

pip install phone-mcp

Configuration example (for Cursor or your AI assistant):

Option A (using uvx):
```json
{
  "mcpServers": {
    "phone-mcp": {
      "command": "uvx",
      "args": [
        "phone-mcp"
      ]
    }
  }
}

Option B (if installed with pip):

{
  "mcpServers": {
    "phone-mcp": {
      "command": "/usr/local/bin/python",
      "args": [
        "-m",
        "phone_mcp"
      ]
    }
  }
}

Notes:

• The path to Python in Option B may differ by system; adjust accordingly (e.g., python3 or a virtual environment path).
• In Cursor, place the configuration in ~/.cursor/mcp.json as described in the docs.

Tips and common issues:

• Ensure ADB is properly installed and available in your system PATH.
• Verify USB debugging is enabled on the Android device and that you have granted any required permissions when prompted.
• Some device manufacturers implement custom UIs that may affect certain UI automation features; rely on the most reliable methods such as launch by package/activity when possible.
• If app launch or activity launching fails, use the full package and activity name with the launch command (e.g., phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity).
• For Cursor integration, use the recommended JSON configuration to point to the installed phone-mcp module.
• If using pipx or other environments, ensure the module name matches the installation used (phone_mcp vs. phone-mcp).
• When troubleshooting, check that the connected device appears in adb devices and that USB connection is stable.