https://github.com/hao-cyber/phone-mcp
A phone control plugin for MCP that allows you to control your Android phone through ADB commands to connect any human
https://github.com/hao-cyber/phone-mcp
agent android mcp mcp-server phone-mcp
Last synced: 6 months ago
JSON representation
A phone control plugin for MCP that allows you to control your Android phone through ADB commands to connect any human
- Host: GitHub
- URL: https://github.com/hao-cyber/phone-mcp
- Owner: hao-cyber
- License: apache-2.0
- Created: 2025-04-09T15:40:38.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-04-17T19:25:26.000Z (6 months ago)
- Last Synced: 2025-04-18T13:37:39.117Z (6 months ago)
- Topics: agent, android, mcp, mcp-server, phone-mcp
- Language: Python
- Homepage:
- Size: 162 KB
- Stars: 18
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - **phone-mcp** - A phone control plugin for MCP that allows you to control your Android phone through ADB commands to connect any human `python` `agent` `android` `mcp` `mcp-server` `pip install git+https://github.com/hao-cyber/phone-mcp` (AI/ML)
- awesome-mcp-servers - **phone-mcp** - A phone control plugin for MCP that allows you to control your Android phone through ADB commands to connect any human `python` `agent` `android` `mcp` `mcp-server` `pip install git+https://github.com/hao-cyber/phone-mcp` (AI/ML)
- mcp-index - Phone Control Plugin - Control an Android phone using ADB commands for tasks such as making calls, sending messages, managing contacts, and automating various phone operations directly from a computer. (IoT and Device Control)
README
# π± Phone MCP Plugin
π A powerful MCP plugin that lets you control your Android phone with ease through ADB commands.
[δΈζζζ‘£](README_zh.md)
## β‘ Quick Start
### π₯ Installation
```bash
pip install phone-mcp
# or use uvx
uvx phone-mcp
```
### π§ Configuration
#### Cursor Setup
Configure in `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"phone-mcp": {
"command": "uvx",
"args": [
"phone-mcp"
]
}
}
}
```
#### Claude Setup
Add to Claude configuration:
```json
{
"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
- πΈ **Media**: Screenshots, screen recording, media control
- π± **Apps**: Launch applications, set alarms, 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, monitor UI changes
- π§ **Screen Analysis**: Structured screen information and unified interaction
- π **Web Browser**: Open URLs in device's default browser
## π οΈ Requirements
- Python 3.7+
- 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"
# Check messages
phone-cli messages --limit 10
# Get contacts
phone-cli contacts --limit 20
```
### Media & Apps
```bash
# Take screenshot
phone-cli screenshot
# Record screen
phone-cli record --duration 30
# Launch app
phone-cli app camera
# Close app
phone-cli close-app com.android.camera
# List installed apps
phone-cli list-apps --filter camera --third-party
# Launch specific activity
phone-cli launch com.android.settings/.Settings
# 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 [parameters]
# Tap on element by text
phone-cli screen-interact tap element_text="Login"
# Tap at coordinates
phone-cli screen-interact tap x=500 y=800
# 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 changes
phone-cli monitor-ui --interval 1 --duration 60
```
### Location & Maps
```bash
# Search nearby POIs with phone numbers
phone-cli get-poi 116.480053,39.987005 --keywords restaurant --radius 1000
```
## π Advanced Usage
### Screen-Driven Automation
The unified screen interaction interface allows intelligent agents to easily:
1. **Analyze the screen**: Get a 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
4. **Monitor changes**: Continuously observe UI changes and respond automatically
## π Documentation
For complete documentation and configuration details, visit our [GitHub repository](https://github.com/hao-cyber/phone-mcp).
## π License
Apache License, Version 2.0