Phone MCP Plugin

A phone control plugin for MCP that allows you to control your Android phone to connect any human.

中文文档

Using Phone MCP in Claude and Cursor

Installation

uvx phone-mcp

Cursor Configuration

Configure in ~/.cursor/mcp.json:

"phone-mcp": {
    "command": "uvx",
    "args": [
        "phone-mcp"
    ]
}

Using in Claude

"phone-mcp": {
    "command": "uvx",
    "args": [
        "phone-mcp"
    ]
}

Claude can directly call the following phone control functions:

• Call Functions: Make calls, end calls, receive incoming calls
• Messaging Functions: Send SMS, receive recent messages
• Contact Functions: Access phone contacts
• Media Functions: Take screenshots, record screen, control media playback
• App Functions: Open applications, set alarms
• System Functions: Get window info, app shortcuts, launch specific activities
• Map Functions: Search for POI information (including phone numbers) by location (requires AMap API key)

Example Commands

Use directly in Claude conversations:

• Check device connection: mcp_phone_mcp_check_device_connection
• Make a phone call: mcp_phone_mcp_call_number
• Send a text message: mcp_phone_mcp_send_text_message
• Get contacts: mcp_phone_mcp_get_contacts
• Take a screenshot: mcp_phone_mcp_take_screenshot
• Get app shortcuts: mcp_phone_mcp_get_app_shortcuts
• Get window info: mcp_phone_mcp_get_current_window
• Launch specific activity: mcp_phone_mcp_launch_activity
• Search POIs by location: mcp_amap_maps_maps_get_poi_info_by_location

No additional configuration is needed. As long as ADB is properly installed and configured, Claude can directly control your Android device.

Installation

Install the package from PyPI:

pip install phone-mcp

Or install with UVX:

uvx phone-mcp

Requirements

• Python 3.7+
• Android device with USB debugging enabled
• ADB installed and configured on your system

ADB Setup (Required)

This package requires ADB (Android Debug Bridge) to be installed on your computer and properly connected to your Android device.

Installing ADB

1. Windows:

   • Download Platform Tools from Google
   • Extract the zip file to a location on your computer (e.g., C:\android-sdk)
   • Add the Platform Tools directory to your PATH environment variable

2. macOS:

   • Install via Homebrew: brew install android-platform-tools
   • Or download Platform Tools from the link above

3. Linux:

   • Ubuntu/Debian: sudo apt-get install adb
   • Fedora: sudo dnf install android-tools
   • Or download Platform Tools from the link above

Connecting Your Android Device

1. Enable USB Debugging:

   • On your Android device, go to Settings > About phone
   • Tap "Build number" seven times to enable Developer options
   • Go back to Settings > System > Developer options
   • Enable "USB debugging"

2. Connect Device:

   • Connect your phone to your computer with a USB cable
   • Accept the USB debugging authorization prompt on your phone
   • Verify the connection by running adb devices in your terminal/command prompt
   • You should see your device listed as "device" (not "unauthorized" or "offline")

3. Troubleshooting:

   • If your device shows as "unauthorized", check for a prompt on your phone
   • If no devices are shown, try:
     • Different USB cable or port
     • Restart ADB server with adb kill-server followed by adb start-server
     • Install manufacturer-specific USB drivers (Windows)

Verifying Connection

Before using this package, verify that ADB can detect your device:

# Check if your device is properly connected
adb devices

# Expected output:
# List of devices attached
# XXXXXXXX    device

Configuration

The plugin includes several configurable options that can be customized:

Country Code

By default, the country code +86 (China) is used when making calls or sending messages. You can change this by editing the config.py file:

# In phone_mcp/config.py
DEFAULT_COUNTRY_CODE = "+1"  # Change to your country code (e.g., "+1" for US)

Map API Key

To use location-based POI search features, you need to set an AMap API key:

# Set environment variable
export AMAP_MAPS_API_KEY="your_api_key_here"

The map features will only be enabled if this environment variable is set.

Storage Paths

Screenshot and recording paths can be customized:

# Screenshot storage location on the device
SCREENSHOT_PATH = "/sdcard/Pictures/Screenshots/"

# Screen recording storage location on the device
RECORDING_PATH = "/sdcard/Movies/"

Command Behavior

Timeouts and auto-retry settings:

# Maximum time (seconds) to wait for a command to complete
COMMAND_TIMEOUT = 30

# Whether to automatically retry connecting to the device
AUTO_RETRY_CONNECTION = True

# Maximum number of connection retry attempts
MAX_RETRY_COUNT = 3

Features

• Make and receive phone calls
• Send and receive text messages
• Take screenshots and record screen
• Control media playback
• Open apps and set alarms
• Check device connection
• Access and manage contacts

Usage

Using as an MCP Plugin

When used as an MCP plugin, the functionality will be available through your MCP interface.

Command Line Interface

The package also provides a command line interface for direct access to phone functions:

# Check device connection (use this first to verify setup)
phone-cli check

# Make a phone call
phone-cli call 1234567890

# End current call
phone-cli hangup

# Send a text message
phone-cli send-sms 1234567890 "Hello from CLI"

# Read/check recent text messages
phone-cli messages --limit 10

# Get contacts
phone-cli contacts

# Take a screenshot
phone-cli screenshot

# Record screen (default 30 seconds)
phone-cli record --duration 10

# Play/pause media
phone-cli media

# Launch an app
phone-cli app camera

# Set an alarm
phone-cli alarm 7 30 --label "Wake up"

# Check for incoming calls
phone-cli incoming

# Get window information
phone-cli window

# Get app shortcuts
phone-cli shortcuts --package com.android.calculator2

# Launch specific activity
phone-cli launch --component com.android.settings/.Settings\$WifiSettingsActivity
# Original command
phone-cli launch-activity --component com.android.settings/.Settings\$WifiSettingsActivity

# Map API commands (only available if AMAP_MAPS_API_KEY is set)
# Get POI information by location
phone-cli get-poi 116.480053,39.987005 --keywords 餐厅 --radius 1000
# Alias for get-poi command
phone-cli map-around 116.480053,39.987005 --keywords 餐厅 --radius 1000

Available Tools

Call Functions

• call_number: Make a phone call
• end_call: End the current call
• receive_incoming_call: Handle incoming calls
• check_device_connection: Check if a device is connected

Messaging Functions

• send_text_message: Send an SMS
• receive_text_messages: Get recent messages

Contact Functions

• get_contacts: Retrieve contacts from the phone

Media Functions

• take_screenshot: Capture screen
• start_screen_recording: Record screen
• play_media: Control media playback

App Functions

• open_app: Launch applications
• set_alarm: Create an alarm

System Functions

• get_current_window: Get information about currently active window
• get_app_shortcuts: Get app shortcuts for specific or all packages
• launch_activity: Launch specific app activities with custom intents

Map Functions

• around_search: Search for POIs around a location
• get_poi_info_by_location: Search for POI information including phone numbers by location (alias available as map-around in CLI)

Development

To contribute to this project:

1. Clone the repository
2. Install development dependencies: pip install -e ".[dev]"
3. Make your changes
4. Run tests: pytest

License

Apache License, Version 2.0