Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hao-cyber--phone-mcp/badge.svg)](/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

i

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)

  1. # πŸ“± Phone MCP Plugin
  2. ![Downloads](https://pepy.tech/badge/phone-mcp)
  3. 🌟 A powerful MCP plugin that lets you control your Android phone with ease through ADB commands.
  4. ## Example
  5. - Based on today's weather by browser, automatically select and play netease music, no confirmation needed
  6. ![play_mucic_x2](https://github.com/user-attachments/assets/58a39b26-6e8b-4f00-8073-3881f657aa5c)
  7. - Call Hao from the contacts. If he doesn't answer, send a text message telling him to come to Meeting Room 101.
  8. ![call_sms_x2](https://github.com/user-attachments/assets/9a155e7c-6dde-4248-b499-0444f19448d0)
  9. [δΈ­ζ–‡ζ–‡ζ‘£](README_zh.md)
  10. ## ⚑ Quick Start
  11. ### πŸ“₯ Installation
  12. Use Python 3.10+ and [uv](https://docs.astral.sh/uv/getting-started/installation/) to run in an isolated environment:
  13. ```bash
  14. uvx --with "mcp<2" --with requests phone-mcp
  15. ```
  16. 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.
  17. For a persistent installation with uv:
  18. ```bash
  19. uv venv --python 3.11 .venv
  20. uv pip install --python .venv/bin/python phone-mcp "mcp<2" requests
  21. .venv/bin/phone-cli --help
  22. ```
  23. Or use Python's built-in virtual environment and pip on Linux/macOS:
  24. ```bash
  25. python3 -m venv .venv
  26. .venv/bin/python -m pip install phone-mcp "mcp<2" requests
  27. .venv/bin/phone-cli --help
  28. ```
  29. 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.
  30. 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.
  31. ### πŸ”§ Configuration
  32. #### AI Assistant Configuration
  33. Configure in your AI assistant configuration (Cursor, Trae, Claude, etc.):
  34. ```json
  35. {
  36. "mcpServers": {
  37. "phone-mcp": {
  38. "command": "uvx",
  39. "args": [
  40. "--with", "mcp<2",
  41. "--with", "requests",
  42. "phone-mcp"
  43. ]
  44. }
  45. }
  46. }
  47. ```
  48. Alternatively, if you installed with pip:
  49. ```json
  50. {
  51. "mcpServers": {
  52. "phone-mcp": {
  53. "command": "/absolute/path/to/.venv/bin/python",
  54. "args": [
  55. "-m",
  56. "phone_mcp"
  57. ]
  58. }
  59. }
  60. }
  61. ```
  62. > **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.
  63. > **Note**: For Cursor, place this configuration in `~/.cursor/mcp.json`
  64. Usage:
  65. - Use commands directly in Claude conversation, for example:
  66. ```
  67. Please call contact hao
  68. ```
  69. ⚠️ Before using, ensure:
  70. - ADB is properly installed and configured
  71. - USB debugging is enabled on your Android device
  72. - Device is connected to computer via USB
  73. ## 🎯 Key Features
  74. - πŸ“ž **Call Functions**: Make calls, end calls, receive incoming calls
  75. - πŸ’¬ **Messaging**: Send and receive SMS, get raw messages
  76. - πŸ‘₯ **Contacts**: Access phone contacts, create new contacts with automated UI interaction
  77. - πŸ“Έ **Media**: Screenshots, screen recording, media control
  78. - πŸ“± **Apps**: Launch applications, launch specific activities with intents, list installed apps, terminate apps
  79. - πŸ”§ **System**: Window info, app shortcuts
  80. - πŸ—ΊοΈ **Maps**: Search POIs with phone numbers
  81. - πŸ–±οΈ **UI Interaction**: Tap, swipe, type text, press keys
  82. - πŸ” **UI Inspection**: Find elements by text, ID, class or description
  83. - πŸ€– **UI Automation**: Wait for elements, scroll to find elements
  84. - 🧠 **Screen Analysis**: Structured screen information and unified interaction
  85. - 🌐 **Web Browser**: Open URLs in device's default browser
  86. - πŸ”„ **UI Monitoring**: Monitor UI changes and wait for specific elements to appear or disappear
  87. ## πŸ› οΈ Requirements
  88. - Python 3.10+
  89. - Android device with USB debugging enabled
  90. - ADB tools
  91. ## πŸ“‹ Basic Commands
  92. ### Device & Connection
  93. ```bash
  94. # Check device connection
  95. phone-cli check
  96. # Get screen size
  97. phone-cli screen-interact find method=clickable
  98. ```
  99. ### Communication
  100. ```bash
  101. # Make a call
  102. phone-cli call 1234567890
  103. # End current call
  104. phone-cli hangup
  105. # Send SMS
  106. phone-cli send-sms 1234567890 "Hello"
  107. # Get received messages (with pagination)
  108. phone-cli messages --limit 10
  109. # Get sent messages (with pagination)
  110. phone-cli sent-messages --limit 10
  111. # Get contacts (with pagination)
  112. phone-cli contacts --limit 20
  113. # Create a new contact with UI automation
  114. phone-cli create-contact "John Doe" "1234567890"
  115. ```
  116. ### Media & Apps
  117. ```bash
  118. # Take screenshot
  119. phone-cli screenshot
  120. # Record screen
  121. phone-cli record --duration 30
  122. # Launch app (may not work on all devices)
  123. phone-cli app camera
  124. # Alternative app launch method using open_app (if app command doesn't work)
  125. phone-cli open_app camera
  126. # Close app
  127. phone-cli close-app com.android.camera
  128. # List installed apps (basic info, faster)
  129. phone-cli list-apps
  130. # List apps with pagination
  131. phone-cli list-apps --page 1 --page-size 10
  132. # List apps with detailed info (slower)
  133. phone-cli list-apps --detailed
  134. # Launch specific activity (reliable method for all devices)
  135. phone-cli launch com.android.settings/.Settings
  136. # Launch app by package name (may not work on all devices)
  137. phone-cli app com.android.contacts
  138. # Alternative launch by package name (if app command doesn't work)
  139. phone-cli open_app com.android.contacts
  140. # Launch app by package and activity (most reliable method)
  141. phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity
  142. # Open URL in default browser
  143. phone-cli open-url google.com
  144. ```
  145. ### Screen Analysis & Interaction
  146. ```bash
  147. # Analyze current screen with structured information
  148. phone-cli analyze-screen
  149. # Unified interaction interface
  150. phone-cli screen-interact <action> [parameters]
  151. # Tap at coordinates
  152. phone-cli screen-interact tap x=500 y=800
  153. # Tap element by text
  154. phone-cli screen-interact tap element_text="Login"
  155. # Tap element by content description
  156. phone-cli screen-interact tap element_content_desc="Calendar"
  157. # Swipe gesture (scroll down)
  158. phone-cli screen-interact swipe x1=500 y1=1000 x2=500 y2=200 duration=300
  159. # Press key
  160. phone-cli screen-interact key keycode=back
  161. # Input text
  162. phone-cli screen-interact text content="Hello World"
  163. # Find elements
  164. phone-cli screen-interact find method=text value="Login" partial=true
  165. # Wait for element
  166. phone-cli screen-interact wait method=text value="Success" timeout=10
  167. # Scroll to find element
  168. phone-cli screen-interact scroll method=text value="Settings" direction=down max_swipes=5
  169. # Monitor UI for changes
  170. phone-cli monitor-ui --interval 0.5 --duration 30
  171. # Monitor UI until specific text appears
  172. phone-cli monitor-ui --watch-for text_appears --text "Welcome"
  173. # Monitor UI until specific element ID appears
  174. phone-cli monitor-ui --watch-for id_appears --id "login_button"
  175. # Monitor UI until specific element class appears
  176. phone-cli monitor-ui --watch-for class_appears --class-name "android.widget.Button"
  177. # Monitor UI changes with output as raw JSON
  178. phone-cli monitor-ui --raw
  179. ```
  180. ### Location & Maps
  181. ```bash
  182. # Search nearby POIs with phone numbers
  183. phone-cli get-poi 116.480053,39.987005 --keywords restaurant --radius 1000
  184. ```
  185. ## πŸ“š Advanced Usage
  186. ### App and Activity Launch
  187. The plugin provides multiple ways to launch apps and activities:
  188. 1. **By App Name** (Two Methods):
  189. ```bash
  190. # Method 1: Using app command (may not work on all devices)
  191. phone-cli app camera
  192. # Method 2: Using open_app command (alternative if app command fails)
  193. phone-cli open_app camera
  194. ```
  195. 2. **By Package Name** (Two Methods):
  196. ```bash
  197. # Method 1: Using app command (may not work on all devices)
  198. phone-cli app com.android.contacts
  199. # Method 2: Using open_app command (alternative if app command fails)
  200. phone-cli open_app com.android.contacts
  201. ```
  202. 3. **By Package and Activity** (Most Reliable Method):
  203. ```bash
  204. # This method works on all devices
  205. phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity
  206. ```
  207. > **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.
  208. ### Contact Creation with UI Automation
  209. The plugin provides a way to create contacts through UI interaction:
  210. ```bash
  211. # Create a new contact with UI automation
  212. phone-cli create-contact "John Doe" "1234567890"
  213. ```
  214. This command will:
  215. 1. Open the contacts app
  216. 2. Navigate to the contact creation interface
  217. 3. Fill in the name and phone number fields
  218. 4. Save the contact automatically
  219. ### Screen-Based Automation
  220. The unified screen interaction interface allows intelligent agents to easily:
  221. 1. **Analyze screens**: Get structured analysis of UI elements and text
  222. 2. **Make decisions**: Based on detected UI patterns and available actions
  223. 3. **Execute interactions**: Through a consistent parameter system
  224. ### UI Monitoring and Automation
  225. The plugin provides powerful UI monitoring capabilities to detect interface changes:
  226. 1. **Basic UI monitoring**:
  227. ```bash
  228. # Monitor any UI changes with custom interval (seconds)
  229. phone-cli monitor-ui --interval 0.5 --duration 30
  230. ```
  231. 2. **Wait for specific elements to appear**:
  232. ```bash
  233. # Wait for text to appear (useful for automated testing)
  234. phone-cli monitor-ui --watch-for text_appears --text "Login successful"
  235. # Wait for specific ID to appear
  236. phone-cli monitor-ui --watch-for id_appears --id "confirmation_dialog"
  237. ```
  238. 3. **Monitor elements disappearing**:
  239. ```bash
  240. # Wait for text to disappear
  241. phone-cli monitor-ui --watch-for text_disappears --text "Loading..."
  242. ```
  243. 4. **Get detailed UI change reports**:
  244. ```bash
  245. # Get raw JSON data with all UI change information
  246. phone-cli monitor-ui --raw
  247. ```
  248. > **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.
  249. ## πŸ“š Detailed Documentation
  250. For complete documentation and configuration details, visit our [GitHub repository](https://github.com/hao-cyber/phone-mcp).
  251. ## 🧰 Tool Documentation
  252. ### Screen Interface API
  253. The plugin provides a powerful screen interface with comprehensive APIs for interacting with the device. Below are the key functions and their parameters:
  254. #### interact_with_screen
  255. ```python
  256. async def interact_with_screen(action: str, params: Dict[str, Any] = None) -> str:
  257. """Execute screen interaction actions"""
  258. ```
  259. - **Parameters:**
  260. - `action`: Type of action ("tap", "swipe", "key", "text", "find", "wait", "scroll")
  261. - `params`: Dictionary with parameters specific to each action type
  262. - **Returns:** JSON string with operation results
  263. **Examples:**
  264. ```python
  265. # Tap by coordinates
  266. result = await interact_with_screen("tap", {"x": 100, "y": 200})
  267. # Tap by element text
  268. result = await interact_with_screen("tap", {"element_text": "Login"})
  269. # Swipe down
  270. result = await interact_with_screen("swipe", {"x1": 500, "y1": 300, "x2": 500, "y2": 1200, "duration": 300})
  271. # Input text
  272. result = await interact_with_screen("text", {"content": "Hello world"})
  273. # Press back key
  274. result = await interact_with_screen("key", {"keycode": "back"})
  275. # Find element by text
  276. result = await interact_with_screen("find", {"method": "text", "value": "Settings", "partial": True})
  277. # Wait for element to appear
  278. result = await interact_with_screen("wait", {"method": "text", "value": "Success", "timeout": 10, "interval": 0.5})
  279. # Scroll to find element
  280. result = await interact_with_screen("scroll", {"method": "text", "value": "Privacy Policy", "direction": "down", "max_swipes": 8})
  281. ```
  282. #### analyze_screen
  283. ```python
  284. async def analyze_screen(include_screenshot: bool = False, max_elements: int = 50) -> str:
  285. """Analyze the current screen and provide structured information about UI elements"""
  286. ```
  287. - **Parameters:**
  288. - `include_screenshot`: Whether to include base64-encoded screenshot in result
  289. - `max_elements`: Maximum number of UI elements to process
  290. - **Returns:** JSON string with detailed screen analysis
  291. #### create_contact
  292. ```python
  293. async def create_contact(name: str, phone: str) -> str:
  294. """Create a new contact with the given name and phone number"""
  295. ```
  296. - **Parameters:**
  297. - `name`: The contact's full name
  298. - `phone`: The phone number for the contact
  299. - **Returns:** JSON string with operation result
  300. - **Location:** This function is found in the 'contacts.py' module and implements UI automation to create contacts
  301. #### launch_app_activity
  302. ```python
  303. async def launch_app_activity(package_name: str, activity_name: Optional[str] = None) -> str:
  304. """Launch an app using package name and optionally an activity name"""
  305. ```
  306. - **Parameters:**
  307. - `package_name`: The package name of the app to launch
  308. - `activity_name`: The specific activity to launch (optional)
  309. - **Returns:** JSON string with operation result
  310. - **Location:** This function is found in the 'apps.py' module
  311. #### launch_intent
  312. ```python
  313. async def launch_intent(intent_action: str, intent_type: Optional[str] = None, extras: Optional[Dict[str, str]] = None) -> str:
  314. """Launch an activity using Android intent system"""
  315. ```
  316. - **Parameters:**
  317. - `intent_action`: The action to perform
  318. - `intent_type`: The MIME type for the intent (optional)
  319. - `extras`: Extra data to pass with the intent (optional)
  320. - **Returns:** JSON string with operation result
  321. - **Location:** This function is found in the 'apps.py' module
  322. ## πŸ“„ License
  323. Apache License, Version 2.0
  324. # Contact Creation Tool
  325. This tool provides a simple way to create contacts on an Android device using ADB.
  326. ## Prerequisites
  327. - Python 3.x
  328. - ADB (Android Debug Bridge) installed and configured
  329. - Android device connected and authorized for ADB
  330. ## Usage
  331. ### Basic Usage
  332. Simply run the script:
  333. ```bash
  334. python create_contact.py
  335. ```
  336. This will create a contact with default values:
  337. - Account name: "δ½ ηš„θ΄¦ζˆ·ε"
  338. - Account type: "com.google"
  339. ### Advanced Usage
  340. You can provide custom account name and type using a JSON string:
  341. ```bash
  342. python create_contact.py '{"account_name": "your_account", "account_type": "com.google"}'
  343. ```
  344. ### Output
  345. The script outputs a JSON object with:
  346. - `success`: boolean indicating if the operation was successful
  347. - `message`: any output or error message from the command
  348. Example success output:
  349. ```json
  350. {"success": true, "message": ""}
  351. ```
  352. ## Error Handling
  353. - If ADB is not available or device is not connected, the script will return an error
  354. - Invalid JSON input will result in an error message
  355. - Any ADB command errors will be captured and returned in the message field
  356. ## Notes
  357. - Make sure your Android device is connected and authorized for ADB use
  358. - The device screen should be unlocked when running the command
  359. - Some devices might require additional permissions to modify contacts
  360. ### Apps & Shortcuts
  361. ```bash
  362. # Get app shortcuts (with pagination)
  363. phone-cli shortcuts --package "com.example.app"
  364. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.