Linux/macOS: Run the following command in terminal:

which python3

or

which python

Windows: Run in Command Prompt (CMD):

where python

Or in PowerShell:

(Get-Command python).Path

Make sure to replace /usr/local/bin/python in the configuration with the full path, for example on Windows it might be C:\Python39\python.exe

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.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_wit