📱 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)
pho

... [View full README on GitHub](https://github.com/hao-cyber/phone-mcp#readme)