📱 Phone MCP Plugin

🌟 A powerful MCP plugin that lets you control your Android phone with ease through ADB commands.

Example

• Based on today's weather by browser, automatically select and play netease music, no confirmation needed

• Call Hao from the contacts. If he doesn't answer, send a text message telling him to come to Meeting Room 101.

中文文档

⚡ Quick Start

📥 Installation

Use Python 3.10+ and uv to run in an isolated environment:

uvx --with "mcp<2" --with requests phone-mcp

The extra dependencies keep existing PyPI releases compatible with the MCP v1 API and provide requests, which the maps module imports. They are declared in the updated source package but are needed for older releases.

For a persistent installation with uv:

uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python phone-mcp "mcp<2" requests
.venv/bin/phone-cli --help

Or use Python's built-in virtual environment and pip on Linux/macOS:

python3 -m venv .venv
.venv/bin/python -m pip install phone-mcp "mcp<2" requests
.venv/bin/phone-cli --help

On Windows, create the environment with py -3 -m venv .venv, then use .venv\Scripts\python.exe and .venv\Scripts\phone-cli.exe instead of the .venv/bin/ paths above.

On Debian/Ubuntu, an externally-managed-environment error means the system Python is managed by the OS. Use uvx or a virtual environment; do not bypass it with sudo pip or --break-system-packages. If venv is unavailable, install python3-venv with your system package manager first.

🔧 Configuration

AI Assistant Configuration

Configure in your AI assistant configuration (Cursor, Trae, Claude, etc.):

{
    "mcpServers": {
        "phone-mcp": {
            "command": "uvx",
            "args": [
                "--with", "mcp<2",
                "--with", "requests",
                "phone-mcp"
            ]
        }
    }
}

Alternatively, if you installed with pip:

{
    "mcpServers": {
        "phone-mcp": {
            "command": "/absolute/path/to/.venv/bin/python",
            "args": [
                "-m",
                "phone_mcp"
            ]
        }
    }
}

Important: Use the absolute path to Python inside the virtual environment where you installed phone-mcp, not the system Python. On Linux/macOS this is /absolute/path/to/.venv/bin/python; on Windows use C:\path\to\.venv\Scripts\python.exe (escape backslashes as \\ in JSON). You do not need to activate the environment before launching your AI assistant.

Note: For Cursor, place this configuration in ~/.cursor/mcp.json

Usage:

• Use commands directly in Claude conversation, for example:

  Please call contact hao
  

⚠️ Before using, ensure:

• ADB is properly installed and configured
• USB debugging is enabled on your Android device
• Device is connected to computer via USB

🎯 Key Features

• 📞 Call Functions: Make calls, end calls, receive incoming calls
• 💬 Messaging: Send and receive SMS, get raw messages
• 👥 Contacts: Access phone contacts, create new contacts with automated UI interaction
• 📸 Media: Screenshots, screen recording, media control
• 📱 Apps: Launch applications, launch specific activities with intents, list installed apps, terminate apps
• 🔧 System: Window info, app shortcuts
• 🗺️ Maps: Search POIs with phone numbers
• 🖱️ UI Interaction: Tap, swipe, type text, press keys
• 🔍 UI Inspection: Find elements by text, ID, class or description
• 🤖 UI Automation: Wait for elements, scroll to find elements
• 🧠 Screen Analysis: Structured screen information and unified interaction
• 🌐 Web Browser: Open URLs in device's default browser
• 🔄 UI Monitoring: Monitor UI changes and wait for specific elements to appear or disappear

🛠️ Requirements

• Python 3.10+
• Android device with USB debugging enabled
• ADB tools

📋 Basic Commands

Device & Connection

# Check device connection
phone-cli check

# Get screen size
phone-cli screen-interact find method=clickable

Communication

# Make a call
phone-cli call 1234567890

# End current call
phone-cli hangup

# Send SMS
phone-cli send-sms 1234567890 "Hello"

# Get received messages (with pagination)
phone-cli messages --limit 10

# Get sent messages (with pagination)
phone-cli sent-messages --limit 10

# Get contacts (with pagination)
phone-cli contacts --limit 20

# Create a new contact with UI automation
phone-cli create-contact "John Doe" "1234567890"

Media & Apps

# Take screenshot
phone-cli screenshot

# Record screen
phone-cli record --duration 30

# Launch app (may not work on all devices)
phone-cli app camera

# Alternative app launch method using open_app (if app command doesn't work)
phone-cli open_app camera

# Close app
phone-cli close-app com.android.camera

# List installed apps (basic info, faster)
phone-cli list-apps

# List apps with pagination
phone-cli list-apps --page 1 --page-size 10

# List apps with detailed info (slower)
phone-cli list-apps --detailed

# Launch specific activity (reliable method for all devices)
phone-cli launch com.android.settings/.Settings

# Launch app by package name (may not work on all devices)
phone-cli app com.android.contacts

# Alternative launch by package name (if app command doesn't work)
phone-cli open_app com.android.contacts

# Launch app by package and activity (most reliable method)
phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity

# Open URL in default browser
phone-cli open-url google.com

Screen Analysis & Interaction

# Analyze current screen with structured information
phone-cli analyze-screen

# Unified interaction interface
phone-cli screen-interact <action> [parameters]

# Tap at coordinates
phone-cli screen-interact tap x=500 y=800

# Tap element by text
phone-cli screen-interact tap element_text="Login"

# Tap element by content description
phone-cli screen-interact tap element_content_desc="Calendar"

# Swipe gesture (scroll down)
phone-cli screen-interact swipe x1=500 y1=1000 x2=500 y2=200 duration=300

# Press key
phone-cli screen-interact key keycode=back

# Input text
phone-cli screen-interact text content="Hello World"

# Find elements
phone-cli screen-interact find method=text value="Login" partial=true

# Wait for element
phone-cli screen-interact wait method=text value="Success" timeout=10

# Scroll to find element
phone-cli screen-interact scroll method=text value="Settings" direction=down max_swipes=5

# Monitor UI for changes
phone-cli monitor-ui --interval 0.5 --duration 30

# Monitor UI until specific text appears
phone-cli monitor-ui --watch-for text_appears --text "Welcome"

# Monitor UI until specific element ID appears
phone-cli monitor-ui --watch-for id_appears --id "login_button"

# Monitor UI until specific element class appears
phone-cli monitor-ui --watch-for class_appears --class-name "android.widget.Button"

# Monitor UI changes with output as raw JSON
phone-cli monitor-ui --raw

Location & Maps

# Search nearby POIs with phone numbers
phone-cli get-poi 116.480053,39.987005 --keywords restaurant --radius 1000

📚 Advanced Usage

App and Activity Launch

The plugin provides multiple ways to launch apps and activities:

1. By App Name (Two Methods):

   # Method 1: Using app command (may not work on all devices)
   phone-cli app camera
   
   # Method 2: Using open_app command (alternative if app command fails)
   phone-cli open_app camera
   

2. By Package Name (Two Methods):

   # Method 1: Using app command (may not work on all devices)
   phone-cli app com.android.contacts
   
   # Method 2: Using open_app command (alternative if app command fails)
   phone-cli open_app com.android.contacts
   

3. By Package and Activity (Most Reliable Method):

   # This method works on all devices
   phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity
   

Note: If you encounter issues with the app or open_app commands, always use the launch command with the full component name (package/activity) for the most reliable operation.

Contact Creation with UI Automation

The plugin provides a way to create contacts through UI interaction:

# Create a new contact with UI automation
phone-cli create-contact "John Doe" "1234567890"

This command will:

1. Open the contacts app
2. Navigate to the contact creation interface
3. Fill in the name and phone number fields
4. Save the contact automatically

Screen-Based Automation

The unified screen interaction interface allows intelligent agents to easily:

1. Analyze screens: Get structured analysis of UI elements and text
2. Make decisions: Based on detected UI patterns and available actions
3. Execute interactions: Through a consistent parameter system

UI Monitoring and Automation

The plugin provides powerful UI monitoring capabilities to detect interface changes:

1. Basic UI monitoring:

   # Monitor any UI changes with custom interval (seconds)
   phone-cli monitor-ui --interval 0.5 --duration 30
   

2. Wait for specific elements to appear:

   # Wait for text to appear (useful for automated testing)
   phone-cli monitor-ui --watch-for text_appears --text "Login successful"
   
   # Wait for specific ID to appear
   phone-cli monitor-ui --watch-for id_appears --id "confirmation_dialog"
   

3. Monitor elements disappearing:

   # Wait for text to disappear
   phone-cli monitor-ui