Overview

Phone MCP Server is an MCP (Model Context Protocol) plugin that exposes an Android phone as a controllable resource for AI agents. Once installed and configured, the server provides a set of “tools” (device actions and sensors) that an MCP-capable agent can call to read state, trigger actions, or automate workflows on a physical Android phone. This lets agents combine model reasoning with direct control of a mobile device for tasks that require real-world interaction.

This is useful for automations and agent workflows where smartphone capabilities are required: media playback based on contextual signals, initiating calls or SMS messages from an agent decision, taking photos or screenshots for visual context, or reading sensor data such as battery level and location. The server follows the MCP pattern for exposing tool-like APIs so developers can plug it into an existing MCP-aware agent stack.

Features

Expose Android device capabilities as MCP tools (actions + sensors)
Control media playback, launch apps, and send intents
Phone calls and SMS message sending support
Capture photos, screenshots, and read gallery items
Access device telemetry: battery, network, location, installed apps
Authentication via API token (configurable)
Designed to be used by MCP-compliant agents and orchestrators

Installation / Configuration

Basic steps (generic, for developers new to the project):

Clone the repository
Build the Android app or server component
Install the APK on a target device (or run in Termux / Android service)
Configure host and API key for MCP clients

Example: clone and run locally (shell)

# Clone the repo
git clone https://github.com/hao-cyber/phone-mcp.git
cd phone-mcp

# Build APK (if Android/Gradle project)
./gradlew assembleRelease

# Install on connected device via ADB
adb install -r app/build/outputs/apk/release/app-release.apk

# Start the service on device (if supported via intent)
adb shell am startservice -n com.example.phone_mcp/.PhoneMcpService

Example: configure a client to talk to the server (JSON config)

{
  "mcp_plugins": [
    {
      "name": "phone-mcp",
      "type": "http",
      "url": "http://192.168.1.10:3000/mcp",
      "api_key": "YOUR_API_KEY_HERE"
    }
  ]
}

Environment variables pattern (example)

export PHONE_MCP_URL="http://192.168.1.10:3000/mcp"
export PHONE_MCP_API_KEY="replace-with-secret"

Adjust host, port, and token to match your device network environment. Your device and MCP agent host must be reachable to each other (same LAN or via port forwarding).

Available Tools / Resources

The server exposes a set of tools an agent can call. Below is a representative table of common tools and parameters — check the repository for exact method names and parameter shapes.

Tool name	Purpose	Key parameters
play_media	Start media playback / play a playlist	source, volume, shuffle
stop_media	Stop/pause playback	—
call	Place a phone call	number
send_sms	Send an SMS	number, message
take_photo	Capture a photo with camera	camera (front/back), quality
screenshot	Capture current screen	format
list_apps	List installed packages	include_system (bool)
get_location	Get current GPS coordinates	accuracy
get_battery	Read battery level and charging status	—
launch_app	Open an app or send an intent	package, activity, extras

Repository and docs:

GitHub: https://github.com/hao-cyber/phone-mcp

Use Cases

Weather-based music playback
- Agent queries an external weather API, decides a mood (e.g., “rainy”), and calls the phone-mcp play_media tool to start a playlist tagged “rainy day” on the device. The agent can set volume and start time.
Automated calls and texts
- An agent monitoring a calendar or alert system can call a contact or send an SMS when certain conditions occur (e.g., “If package delivery failed, call user and send status SMS”). The agent uses call(number) and send_sms(number, message).
Visual verification and evidence collection
- A home automation agent requests a photo or screenshot from the phone to confirm a state (e.g., take_photo(front)) and then processes the image or uploads it to a logging system.
Location-aware reminders
- An agent periodically checks get_location and triggers an action (launch_app or send_sms) when the device enters a geofence.

Example MCP Tool Call (JSON)

Below is a simplified example of how an MCP-style tool call might look when an agent asks the phone to send an SMS:

{
  "tool": "send_sms",
  "args": {
    "number": "+15551234567",
    "message": "Your appointment is at 3pm today."
  }
}

The agent should handle authentication (include API key) and inspect the tool response for success/failure details.

Notes for Developers

Ensure network connectivity and firewall rules allow your agent to reach the phone server endpoint.
Carefully handle API keys and permissions — actions like calling or sending SMS may incur costs or privacy considerations.
Test tools in a controlled environment before deploying automations that interact with third-party services or contacts.

For implementation specifics, exact endpoint shapes, and up-to-date tool lists, consult the repository README and source code at the GitHub link above.

Phone MCP Server: Android Control for AI Agents