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.
Allows installation of the phone-mcp package directly from PyPI using pip.
Provides specific installation instructions for Ubuntu users to install the required ADB tools via apt-get.
📱 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
🔧 Configuration
AI Assistant Configuration
Configure in your AI assistant configuration (Cursor, Trae, Claude, etc.):
Alternatively, if you installed with pip:
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 python3or
which pythonWindows: Run in Command Prompt (CMD):
where pythonOr in PowerShell:
(Get-Command python).PathMake sure to replace
/usr/local/bin/python
in the configuration with the full path, for example on Windows it might beC:\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
Communication
Media & Apps
Screen Analysis & Interaction
Location & Maps
📚 Advanced Usage
App and Activity Launch
The plugin provides multiple ways to launch apps and activities:
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 cameraBy 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.contactsBy 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
oropen_app
commands, always use thelaunch
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:
This command will:
Open the contacts app
Navigate to the contact creation interface
Fill in the name and phone number fields
Save the contact automatically
Screen-Based Automation
The unified screen interaction interface allows intelligent agents to easily:
Analyze screens: Get structured analysis of UI elements and text
Make decisions: Based on detected UI patterns and available actions
Execute interactions: Through a consistent parameter system
UI Monitoring and Automation
The plugin provides powerful UI monitoring capabilities to detect interface changes:
Basic UI monitoring:
# Monitor any UI changes with custom interval (seconds) phone-cli monitor-ui --interval 0.5 --duration 30Wait 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"Monitor elements disappearing:
# Wait for text to disappear phone-cli monitor-ui --watch-for text_disappears --text "Loading..."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
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:
analyze_screen
Parameters:
include_screenshot
: Whether to include base64-encoded screenshot in resultmax_elements
: Maximum number of UI elements to process
Returns: JSON string with detailed screen analysis
create_contact
Parameters:
name
: The contact's full namephone
: 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
Parameters:
package_name
: The package name of the app to launchactivity_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
Parameters:
intent_action
: The action to performintent_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:
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:
Output
The script outputs a JSON object with:
success
: boolean indicating if the operation was successfulmessage
: any output or error message from the command
Example success output:
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
This server cannot be installed
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.
Related MCP Servers
- AsecurityAlicenseAqualityA 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 -8240Apache 2.0
- -securityAlicense-qualityPhonePi MCP enables seamless integration between desktop AI tools and your smartphone, providing 23+ direct actions including SMS messaging, phone calls, contact management, snippet creation and search, clipboard sharing, notifications, battery status checks, and remote device controls.Last updated -23MIT License
- -securityFlicense-qualityA FastMCP framework-based server providing Android device automation control capabilities, enabling UI interactions, device management, and application control through natural language.Last updated -10
- -securityAlicense-qualityA collection of Apple-native tools for the MCP protocol that enables AI assistants to interact with Apple applications including Messages, Notes, Contacts, Mail, Reminders, Calendar, and Maps.