This MCP server provides a powerful way to control your Android phone through ADB commands, allowing AI assistants to interact with your phone for calls, messaging, contacts management, and more.
# Run directly with uvx (recommended)
uvx phone-mcp
# Or install with uv
uv pip install phone-mcp
# Or install with pip
pip install phone-mcp
Configure in your AI assistant configuration (Cursor, Trae, Claude, etc.):
{
"mcpServers": {
"phone-mcp": {
"command": "uvx",
"args": [
"phone-mcp"
]
}
}
}
If you installed with pip instead:
{
"mcpServers": {
"phone-mcp": {
"command": "/usr/local/bin/python",
"args": [
"-m",
"phone_mcp"
]
}
}
}
Important: You need to modify the Python path according to your system:
which python3 or which python in terminalwhere python in CMD or (Get-Command python).Path in PowerShellNote: For Cursor, place this configuration in ~/.cursor/mcp.json
Before using, ensure you have:
# Check device connection
phone-cli check
# Get screen size
phone-cli screen-interact find method=clickable
# Make a call
phone-cli call 1234567890
# End current call
phone-cli hangup
# Send SMS
phone-cli send-sms 1234567890 "Hello"
# Get received messages
phone-cli messages --limit 10
# Get contacts
phone-cli contacts --limit 20
# Create a new contact
phone-cli create-contact "John Doe" "1234567890"
# Take screenshot
phone-cli screenshot
# Record screen
phone-cli record --duration 30
# Launch app
phone-cli app camera
# Alternative app launch method
phone-cli open_app camera
# Close app
phone-cli close-app com.android.camera
# List installed apps
phone-cli list-apps
# Launch specific activity
phone-cli launch com.android.settings/.Settings
# Open URL in default browser
phone-cli open-url google.com
# Analyze current screen
phone-cli analyze-screen
# Tap at coordinates
phone-cli screen-interact tap x=500 y=800
# Tap element by text
phone-cli screen-interact tap element_text="Login"
# Swipe gesture (scroll down)
phone-cli screen-interact swipe x1=500 y1=1000 x2=500 y2=200 duration=300
# Input text
phone-cli screen-interact text content="Hello World"
# Find elements
phone-cli screen-interact find method=text value="Login" partial=true
# Wait for element
phone-cli screen-interact wait method=text value="Success" timeout=10
# Search nearby POIs with phone numbers
phone-cli get-poi 116.480053,39.987005 --keywords restaurant --radius 1000
The plugin provides multiple ways to launch apps:
# By app name
phone-cli app camera
phone-cli open_app camera
# By package name
phone-cli app com.android.contacts
phone-cli open_app com.android.contacts
# By package and activity (most reliable)
phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity
Note: If you encounter issues, the launch command with full component name is most reliable.
Monitor UI changes and wait for specific elements:
# Monitor any UI changes
phone-cli monitor-ui --interval 0.5 --duration 30
# Wait for text to appear
phone-cli monitor-ui --watch-for text_appears --text "Login successful"
# Wait for text to disappear
phone-cli monitor-ui --watch-for text_disappears --text "Loading..."
# Get detailed UI change reports
phone-cli monitor-ui --raw
# Create a new contact with UI automation
phone-cli create-contact "John Doe" "1234567890"
This command will automatically navigate through the contact creation interface.
The plugin provides a comprehensive API for screen interactions:
phone-cli screen-interact tap x=100 y=200 or tap element_text="Login"phone-cli screen-interact swipe x1=500 y1=300 x2=500 y2=1200 duration=300phone-cli screen-interact text content="Hello world"phone-cli screen-interact key keycode="back"phone-cli screen-interact find method="text" value="Settings" partial=truephone-cli screen-interact wait method="text" value="Success" timeout=10phone-cli screen-interact scroll method="text" value="Privacy" direction="down" max_swipes=8# Get detailed information about the current screen
phone-cli analyze-screen
This provides structured information about UI elements and text on the screen, useful for intelligent agents to make decisions.
For more detailed documentation and examples, visit the GitHub repository.
To add this MCP server to Claude Code, run this command in your terminal:
claude mcp add-json "phone-mcp" '{"command":"uvx","args":["phone-mcp"]}'See the official Claude Code MCP documentation for more details.
There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.
If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.
To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".
When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:
{
"mcpServers": {
"phone-mcp": {
"command": "uvx",
"args": [
"phone-mcp"
]
}
}
}To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.
Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.
The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.
You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.
To add this MCP server to Claude Desktop:
1. Find your configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json2. Add this to your configuration file:
{
"mcpServers": {
"phone-mcp": {
"command": "uvx",
"args": [
"phone-mcp"
]
}
}
}3. Restart Claude Desktop for the changes to take effect