Skip to main content
Glama
Sign In
enesjakozh

Phone MCP Plugin

by hao-cyber
GitHub
Python
Apache 2.0
2
  • Apple
  • Linux
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Integrations

  • Enables controlling Android phones through ADB, allowing functions like making calls, sending messages, accessing contacts, taking screenshots, recording screens, opening apps, and performing system operations.

  • Offers specific installation instructions for Fedora users to install the required ADB tools via the package manager.

  • Provides macOS users with Homebrew installation instructions for the required Android platform tools.

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

A plugin for MCP that enables AI assistants to control Android phones, allowing functions like making calls, sending messages, taking screenshots, and accessing contacts through natural language commands.

  1. Using Phone MCP in Claude and Cursor
    1. Installation
    2. Cursor Configuration
    3. Using in Claude
    4. Example Commands
  2. Installation
    1. Requirements
      1. ADB Setup (Required)
        1. Installing ADB
        2. Connecting Your Android Device
        3. Verifying Connection
      2. Configuration
        1. Country Code
        2. Map API Key
        3. Storage Paths
        4. Command Behavior
      3. Features
        1. Usage
          1. Using as an MCP Plugin
          2. Command Line Interface
        2. Available Tools
          1. Call Functions
          2. Messaging Functions
          3. Contact Functions
          4. Media Functions
          5. App Functions
          6. System Functions
          7. Map Functions
        3. Development
          1. License
            ID: t1dxykaybp