Phone MCP Plugin

📱 手机MCP插件

🌟 一个强大的MCP插件，让您通过ADB命令轻松控制您的Android手机。

示例

• 通过浏览器根据今天的天气，自动选择并播放网易音乐，无需确认

• 从联系人处给郝打电话。如果他不回答，发短信告诉他到101会议室来。

中文文档

⚡ 快速开始

📥 安装

# 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

🔧 配置

AI助手配置

在AI助手配置中进行配置（Cursor、Trae、Claude等）：

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

或者，如果您使用pip安装：

{
    "mcpServers": {
        "phone-mcp": {
            "command": "/usr/local/bin/python",
            "args": [
                "-m",
                "phone_mcp"
            ]
        }
    }
}

重要：路径 /usr/local/bin/python 在上面的配置中是Python解释器的路径。您需要根据系统上实际的Python安装位置对其进行修改。以下是如何在不同操作系统上找到Python路径： Linux/macOS: 在终端中运行以下命令： ``bash which python3 ` 或 `bash which python ` **视窗**: 在命令提示符（CMD）中运行： `cmd where python ` 或者在PowerShell中： `powershell (Get-Command python).Path ` 确保更换 /usr/local/bin/python 在具有完整路径的配置中，例如在Windows上，它可能是 C:\Python39\python.exe`

备注：对于Cursor，将此配置放置在 ~/.cursor/mcp.json

用途：

• 在Claude对话中直接使用命令，例如：

  Please call contact hao

⚠️ 使用前，请确保：

• ADB安装和配置正确
• 您的Android设备上已启用USB调试
• 设备通过USB连接到计算机

🎯 主要特点

• 📞 调用函数：拨打电话、结束通话、接听来电
• 💬 消息传递：发送和接收短信，获取原始消息
• 👥 联系人：访问电话联系人，通过自动UI交互创建新联系人
• 📸 媒体：屏幕截图、屏幕录制、媒体控制
• 📱 应用：启动应用程序，启动具有意图的特定活动，列出已安装的应用程序，终止应用程序
• 🔧 系统：窗口信息、应用快捷方式
• 🗺️ 地图：使用电话号码搜索POI
• 🖱️ UI交互：点击、滑动、键入文本、按键
• 🔍 UI检查：按文本、ID、类或描述查找元素
• 🤖 UI自动化：等待元素，滚动以查找元素
• 🧠 筛分分析：结构化的屏幕信息和统一的交互
• 🌐 Web浏览器：在设备的默认浏览器中打开URL
• 🔄 UI监控：监视UI更改并等待特定元素出现或消失

🛠️ 需求

• Python 3.7+
• 启用USB调试的Android设备
• ADB工具

📋 基本命令

设备和连接

# 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 (with pagination)
phone-cli messages --limit 10

# Get sent messages (with pagination)
phone-cli sent-messages --limit 10

# Get contacts (with pagination)
phone-cli contacts --limit 20

# Create a new contact with UI automation
phone-cli create-contact "John Doe" "1234567890"

媒体和应用程序

# Take screenshot
phone-cli screenshot

# Record screen
phone-cli record --duration 30

# Launch app (may not work on all devices)
phone-cli app camera

# Alternative app launch method using open_app (if app command doesn't work)
phone-cli open_app camera

# Close app
phone-cli close-app com.android.camera

# List installed apps (basic info, faster)
phone-cli list-apps

# List apps with pagination
phone-cli list-apps --page 1 --page-size 10

# List apps with detailed info (slower)
phone-cli list-apps --detailed

# Launch specific activity (reliable method for all devices)
phone-cli launch com.android.settings/.Settings

# Launch app by package name (may not work on all devices)
phone-cli app com.android.contacts

# Alternative launch by package name (if app command doesn't work)
phone-cli open_app com.android.contacts

# Launch app by package and activity (most reliable method)
phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity

# Open URL in default browser
phone-cli open-url google.com

屏幕分析与交互

# Analyze current screen with structured information
phone-cli analyze-screen

# Unified interaction interface
phone-cli screen-interact  [parameters]

# Tap at coordinates
phone-cli screen-interact tap x=500 y=800

# Tap element by text
phone-cli screen-interact tap element_text="Login"

# Tap element by content description
phone-cli screen-interact tap element_content_desc="Calendar"

# Swipe gesture (scroll down)
phone-cli screen-interact swipe x1=500 y1=1000 x2=500 y2=200 duration=300

# Press key
phone-cli screen-interact key keycode=back

# 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

# Scroll to find element
phone-cli screen-interact scroll method=text value="Settings" direction=down max_swipes=5

# Monitor UI for changes
phone-cli monitor-ui --interval 0.5 --duration 30

# Monitor UI until specific text appears
phone-cli monitor-ui --watch-for text_appears --text "Welcome"

# Monitor UI until specific element ID appears
phone-cli monitor-ui --watch-for id_appears --id "login_button"

# Monitor UI until specific element class appears
phone-cli monitor-ui --watch-for class_appears --class-name "android.widget.Button"

# Monitor UI changes with output as raw JSON
phone-cli monitor-ui --raw

位置和地图

# Search nearby POIs with phone numbers
phone-cli get-poi 116.480053,39.987005 --keywords restaurant --radius 1000

📚 高级用法

应用程序和活动启动

该插件提供了多种启动应用程序和活动的方法：

1. 按应用程序名称 （两种方法）：

   # Method 1: Using app command (may not work on all devices)
   phone-cli app camera

   # Method 2: Using open_app command (alternative if app command fails)
   phone-cli open_app camera

1. 按包名称 （两种方法）：

   # Method 1: Using app command (may not work on all devices)
   phone-cli app com.android.contacts

   # Method 2: Using open_app command (alternative if app command fails)
   phone-cli open_app com.android.contacts

1. 按套餐和活动 （最可靠的方法）：

   # This method works on all devices
   phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity

备注：如果您遇到问题 app 或 open_app 命令，始终使用 launch 使用完整组件名称（包/活动）的命令，以实现最可靠的操作。

使用UI自动化创建联系人

该插件提供了一种通过UI交互创建联系人的方法：

# Create a new contact with UI automation
phone-cli create-contact "John Doe" "1234567890"

此命令将：

1. 打开联系人应用程序
2. 导航到联系人创建界面
3. 填写姓名和电话号码字段
4. 自动保存联系人

基于屏幕的自动化

统一的屏幕交互界面使智能代理能够轻松：

1. 分析屏幕：获取UI元素和文本的结构化分析
2. 做决定：基于检测到的UI模式和可用操作
3. 执行交互：通过一致的参数系统

UI监控和自动化

该插件提供强大的UI监控功能来检测界面更改：

1. 基本UI监控:

   # Monitor any UI changes with custom interval (seconds)
   phone-cli monitor-ui --interval 0.5 --duration 30

1. 等待特定元素出现:

   # Wait for text to appear (useful for automated testing)
   phone-cli monitor-ui --watch-for text_appears --text "Login successful"

   # Wait for specific ID to appear
   phone-cli monitor-ui --watch-for id_appears --id "confirmation_dialog"

1. 监控元素消失:

   # Wait for text to disappear
   phone-cli monitor-ui --watch-for text_disappears --text "Loading..."

1. 获取详细的UI更改报告:

   # Get raw JSON data with all UI change information
   phone-cli monitor-ui --raw

小贴士：UI监控对于自动化脚本等待加载屏幕完成或确认操作已在UI中生效特别有用。

📚 详细文件

有关完整的文档和配置详细信息，请访问我们的 .

🧰 工具文档

屏幕界面API

该插件提供了一个强大的屏幕界面，具有与设备交互的全面API。以下是关键功能及其参数：

与屏幕交互

async def interact_with_screen(action: str, params: Dict[str, Any] = None) -> str:
    """Execute screen interaction actions"""

• 参数：

- action：操作类型（“点击”、“滑动”、“按键”、“文本”、“查找”、“等待”、“滚动”） - params：具有特定于每种操作类型的参数的字典

• 退货： 带有操作结果的JSON字符串

示例：

# Tap by coordinates
result = await interact_with_screen("tap", {"x": 100, "y": 200})

# Tap by element text
result = await interact_with_screen("tap", {"element_text": "Login"})

# Swipe down
result = await interact_with_screen("swipe", {"x1": 500, "y1": 300, "x2": 500, "y2": 1200, "duration": 300})

# Input text
result = await interact_with_screen("text", {"content": "Hello world"})

# Press back key
result = await interact_with_screen("key", {"keycode": "back"})

# Find element by text
result = await interact_with_screen("find", {"method": "text", "value": "Settings", "partial": True})

# Wait for element to appear
result = await interact_with_screen("wait", {"method": "text", "value": "Success", "timeout": 10, "interval": 0.5})

# Scroll to find element
result = await interact_with_screen("scroll", {"method": "text", "value": "Privacy Policy", "direction": "down", "max_swipes": 8})

分析屏幕

async def analyze_screen(include_screenshot: bool = False, max_elements: int = 50) -> str:
    """Analyze the current screen and provide structured information about UI elements"""

• 参数：

- include_screenshot：结果中是否包含base64编码的截图 - max_elements：要处理的UI元素的最大数量

• 退货： 带有详细屏幕分析的JSON字符串

create_contact

async def create_contact(name: str, phone: str) -> str:
    """Create a new contact with the given name and phone number"""

• 参数：

- name：联系人的全名 - phone：联系人的电话号码

• 退货： 带运算结果的JSON字符串
• 地点： 此函数位于“contacts.py”模块中，实现了UI自动化以创建联系人

launch_app_活动

async def launch_app_activity(package_name: str, activity_name: Optional[str] = None) -> str:
    """Launch an app using package name and optionally an activity name"""

• 参数：

- package_name：要启动的应用程序的包名称 - activity_name：要启动的具体活动（可选）

• 退货： 带运算结果的JSON字符串
• 地点： 此函数位于“apps.py”模块中

发射帐篷

async def launch_intent(intent_action: str, intent_type: Optional[str] = None, extras: Optional[Dict[str, str]] = None) -> str:
    """Launch an activity using Android intent system"""

• 参数：

- intent_action：要执行的操作 - intent_type：意图的MIME类型（可选） - extras：随意图传递的额外数据（可选）

• 退货： 带运算结果的JSON字符串
• 地点： 此函数位于“apps.py”模块中

📄 许可证

Apache许可证，版本2.0

联系人创建工具

此工具提供了一种使用ADB在Android设备上创建联系人的简单方法。

先决条件

• Python 3.x
• ADB（安卓调试桥）已安装并配置
• 已连接并授权ADB的Android设备

用法

基本用法

只需运行脚本：

python create_contact.py

这将创建一个具有默认值的联系人：

• Account name: "你的账户名"
• 帐户类型：“com.google”

高级用法

您可以使用JSON字符串提供自定义帐户名和类型：

python create_contact.py '{"account_name": "your_account", "account_type": "com.google"}'

输出

该脚本输出一个JSON对象，其中包含：

• success：boolean表示操作是否成功
• message：命令的任何输出或错误消息

成功输出示例：

{"success": true, "message": ""}

错误处理

• 如果ADB不可用或设备未连接，脚本将返回错误
• 无效的JSON输入将导致错误消息
• 任何ADB命令错误都将被捕获并返回到消息字段中

备注

• 确保您的Android设备已连接并授权ADB使用
• 运行命令时，设备屏幕应解锁
• 某些设备可能需要额外的权限来修改联系人

应用程序和快捷方式

# Get app shortcuts (with pagination)
phone-cli shortcuts --package "com.example.app"