phone-mcp
A phone control plugin for MCP that allows you to control your Android phone through ADB commands to connect any human
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/hao-cyber--phone-mcp)HTML
<a href="/listings/hao-cyber--phone-mcp"><img src="/api/listings/hao-cyber--phone-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
π₯ Installation
Use Python 3.10+ and [uv](https://docs.astral.sh/uv/getting-started/installation/) 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
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md Β· README Β· 496 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # π± 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.
- 
- [δΈζζζ‘£](README_zh.md)
- ## β‘ Quick Start
- ### π₯ Installation
- Use Python 3.10+ and [uv](https://docs.astral.sh/uv/getting-started/installation/) to run in an isolated environment:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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.):
- ```json
- {
- "mcpServers": {
- "phone-mcp": {
- "command": "uvx",
- "args": [
- "--with", "mcp<2",
- "--with", "requests",
- "phone-mcp"
- ]
- }
- }
- }
- ```
- Alternatively, if you installed with pip:
- ```json
- {
- "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
- ```bash
- # Check device connection
- phone-cli check
- # Get screen size
- phone-cli screen-interact find method=clickable
- ```
- ### Communication
- ```bash
- # 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
- ```bash
- # 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
- ```bash
- # 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
- ```bash
- # 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):
- ```bash
- # 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):
- ```bash
- # 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):
- ```bash
- # 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:
- ```bash
- # 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**:
- ```bash
- # Monitor any UI changes with custom interval (seconds)
- phone-cli monitor-ui --interval 0.5 --duration 30
- ```
- 2. **Wait for specific elements to appear**:
- ```bash
- # 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**:
- ```bash
- # Wait for text to disappear
- phone-cli monitor-ui --watch-for text_disappears --text "Loading..."
- ```
- 4. **Get detailed UI change reports**:
- ```bash
- # 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](https://github.com/hao-cyber/phone-mcp).
- ## π§° 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
- ```python
- 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:**
- ```python
- # 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
- ```python
- 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
- ```python
- 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
- ```python
- 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
- ```python
- 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:
- ```bash
- 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:
- ```bash
- 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:
- ```json
- {"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
- ```bash
- # Get app shortcuts (with pagination)
- phone-cli shortcuts --package "com.example.app"
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itβs helped, pass it on.