phone-mcp 0.3.4

A phone control plugin for MCP that allows you to control your Android phone through ADB commands to connect any human

📱 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

# Install with pip
pip install phone-mcp

# Or install with uv
uv install phone-mcp

🔧 Configuration

Cursor Setup

Configure in ~/.cursor/mcp.json:

For pip installation:

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

For uv installation:

{
    "mcpServers": {
        "phone-mcp": {
            "command": "uvx",
            "args": [
                "phone-mcp"
            ]
        }
    }
}

Trae Setup

Configure in Trae configuration:

For pip installation:

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

For uv installation:

{
    "mcpServers": {
        "phone-mcp": {
            "command": "uvx",
            "args": [
                "phone-mcp"
            ]
        }
    }
}

Claude Setup

Add to Claude configuration:

For pip installation:

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

For uv installation:

{
    "mcpServers": {
        "phone-mcp": {
            "command": "uvx",
            "args": [
                "phone-mcp"
            ]
        }
    }
}

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.7+
• 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 --watch-for text_disappears --text "Loading..."
   

4. Get detailed UI change reports:

   # Get raw JSON data with all UI change information
   phone-cli monitor-ui --raw
   

Tip: UI monitoring is especially useful for automation scripts to wait for loading screens to complete or confirm that actions have taken effect in the UI.

📚 Detailed Documentation

For complete documentation and configuration details, visit our GitHub repository.

🧰 Tool Documentation

Screen Interface API

The plugin provides a powerful screen interface with comprehensive APIs for interacting with the device. Below are the key functions and their parameters:

interact_with_screen

async def interact_with_screen(action: str, params: Dict[str, Any] = None) -> str:
    """Execute screen interaction actions"""

• Parameters:
  • action: Type of action ("tap", "swipe", "key", "text", "find", "wait", "scroll")
  • params: Dictionary with parameters specific to each action type
• Returns: JSON string with operation results

Examples:

# Tap by coordinates
result = await interact_with_screen("tap", {"x": 100, "y": 200})

# Tap by element text
result = await interact_with_screen("tap", {"element_text": "Login"})

# Swipe down
result = await interact_with_screen("swipe", {"x1": 500, "y1": 300, "x2": 500, "y2": 1200, "duration": 300})

# Input text
result = await interact_with_screen("text", {"content": "Hello world"})

# Press back key
result = await interact_with_screen("key", {"keycode": "back"})

# Find element by text
result = await interact_with_screen("find", {"method": "text", "value": "Settings", "partial": True})

# Wait for element to appear
result = await interact_with_screen("wait", {"method": "text", "value": "Success", "timeout": 10, "interval": 0.5})

# Scroll to find element
result = await interact_with_screen("scroll", {"method": "text", "value": "Privacy Policy", "direction": "down", "max_swipes": 8})

analyze_screen

async def analyze_screen(include_screenshot: bool = False, max_elements: int = 50) -> str:
    """Analyze the current screen and provide structured information about UI elements"""

• Parameters:
  • include_screenshot: Whether to include base64-encoded screenshot in result
  • max_elements: Maximum number of UI elements to process
• Returns: JSON string with detailed screen analysis

create_contact

async def create_contact(name: str, phone: str) -> str:
    """Create a new contact with the given name and phone number"""

• Parameters:
  • name: The contact's full name
  • phone: The phone number for the contact
• Returns: JSON string with operation result
• Location: This function is found in the 'contacts.py' module and implements UI automation to create contacts

launch_app_activity

async def launch_app_activity(package_name: str, activity_name: Optional[str] = None) -> str:
    """Launch an app using package name and optionally an activity name"""

• Parameters:
  • package_name: The package name of the app to launch
  • activity_name: The specific activity to launch (optional)
• Returns: JSON string with operation result
• Location: This function is found in the 'apps.py' module

launch_intent

async def launch_intent(intent_action: str, intent_type: Optional[str] = None, extras: Optional[Dict[str, str]] = None) -> str:
    """Launch an activity using Android intent system"""

• Parameters:
  • intent_action: The action to perform
  • intent_type: The MIME type for the intent (optional)
  • extras: Extra data to pass with the intent (optional)
• Returns: JSON string with operation result
• Location: This function is found in the 'apps.py' module

📄 License

Apache License, Version 2.0

Contact Creation Tool

This tool provides a simple way to create contacts on an Android device using ADB.

Prerequisites

• Python 3.x
• ADB (Android Debug Bridge) installed and configured
• Android device connected and authorized for ADB

Usage

Basic Usage

Simply run the script:

python create_contact.py

This will create a contact with default values:

• Account name: "你的账户名"
• Account type: "com.google"

Advanced Usage

You can provide custom account name and type using a JSON string:

python create_contact.py '{"account_name": "your_account", "account_type": "com.google"}'

Output

The script outputs a JSON object with:

• success: boolean indicating if the operation was successful
• message: any output or error message from the command

Example success output:

{"success": true, "message": ""}

Error Handling

• If ADB is not available or device is not connected, the script will return an error
• Invalid JSON input will result in an error message
• Any ADB command errors will be captured and returned in the message field

Notes

• Make sure your Android device is connected and authorized for ADB use
• The device screen should be unlocked when running the command
• Some devices might require additional permissions to modify contacts

Apps & Shortcuts

# Get app shortcuts (with pagination)
phone-cli shortcuts --package "com.example.app"