Phone MCP Plugin

Apache 2.0
26
  • Apple
  • Linux

Integrations

  • Enables controlling Android phones through ADB, allowing functions like making calls, sending messages, accessing contacts, taking screenshots, recording screens, opening apps, and performing system operations.

  • Offers specific installation instructions for Fedora users to install the required ADB tools via the package manager.

  • Provides macOS users with Homebrew installation instructions for the required Android platform tools.

📱 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

# Run directly with uvx (recommended, part of uv, no separate installation needed) uvx phone-mcp # Or install with uv uv pip install phone-mcp # Or install with pip pip install phone-mcp

🔧 Configuration

AI Assistant Configuration

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

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

Alternatively, if you installed with pip:

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

Important: The path /usr/local/bin/python in the configuration above is the path to the Python interpreter. You need to modify it according to the actual Python installation location on your system. Here's how to find the Python path on different operating systems:

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_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"
-
security - not tested
A
license - permissive license
-
quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

A plugin for MCP that enables AI assistants to control Android phones, allowing functions like making calls, sending messages, taking screenshots, and accessing contacts through natural language commands.

  1. Example
    1. ⚡ Quick Start
      1. 📥 Installation
      2. 🔧 Configuration
    2. 🎯 Key Features
      1. 🛠️ Requirements
        1. 📋 Basic Commands
          1. Device & Connection
          2. Communication
          3. Media & Apps
          4. Screen Analysis & Interaction
          5. Location & Maps
        2. 📚 Advanced Usage
          1. App and Activity Launch
          2. Contact Creation with UI Automation
          3. Screen-Based Automation
          4. UI Monitoring and Automation
        3. 📚 Detailed Documentation
          1. 🧰 Tool Documentation
            1. Screen Interface API
          2. 📄 License
            1. Contact Creation Tool
              1. Prerequisites
              2. Usage
              3. Error Handling
              4. Notes

            Related MCP Servers

            • -
              security
              A
              license
              -
              quality
              A Model Context Protocol (MCP) integration that allows AI assistants to control Home Assistant devices by searching for entities and controlling devices through natural language commands.
              Last updated -
              10
              Python
              MIT License
              • Linux
              • Apple
            • A
              security
              A
              license
              A
              quality
              A Model Context Protocol (MCP) server that enables AI assistants to control and interact with Android devices, allowing for device management, app debugging, system analysis, and UI automation through natural language commands.
              Last updated -
              29
              30
              Python
              Apache 2.0
              • Linux
              • Apple
            • -
              security
              A
              license
              -
              quality
              A Model Context Protocol server that enables AI assistants to interact with Android devices through ADB, allowing for automated device management, app installation, file transfers, and screenshot capture.
              Last updated -
              11
              2
              JavaScript
              ISC License
              • Linux
              • Apple
            • -
              security
              A
              license
              -
              quality
              An MCP server that bridges AI agents with GUI automation capabilities, allowing them to control mouse, keyboard, windows, and take screenshots to interact with desktop applications.
              Last updated -
              Python
              MIT License
              • Apple
              • Linux

            View all related MCP servers

            ID: t1dxykaybp