📱 Phone MCP Plugin

📱 Phone MCP Plugin

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

示例

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

• 给联系人中的 Hao 打电话。如果他没有接听，就给他发送短信，告诉他到 101 会议室来。

中文文档

⚡ 快速开始

📥 安装

使用 Python 3.10+ 和 uv 在隔离环境中运行：

uvx --with "mcp<2" --with requests phone-mcp

额外依赖可确保现有的 PyPI 发行版与 MCP v1 API 兼容，并提供地图模块导入的 requests。这些依赖已在更新后的源代码包中声明，但旧版本仍需要它们。

使用 uv 进行持久安装：

uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python phone-mcp "mcp<2" requests
.venv/bin/phone-cli --help

或者在 Linux/macOS 上使用 Python 内置的虚拟环境和 pip：

python3 -m venv .venv
.venv/bin/python -m pip install phone-mcp "mcp<2" requests
.venv/bin/phone-cli --help

在 Windows 上，使用 py -3 -m venv .venv 创建环境，然后使用 .venv\Scripts\python.exe 和 .venv\Scripts\phone-cli.exe，代替上述 .venv/bin/ 路径。

在 Debian/Ubuntu 上，出现 externally-managed-environment 错误表示系统 Python 由操作系统管理。请使用 uvx 或虚拟环境；不要使用 sudo pip 或 --break-system-packages 绕过限制。如果无法使用 venv，请先通过系统包管理器安装 python3-venv。

🔧 配置

AI 助手配置

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

{
    "mcpServers": {
        "phone-mcp": {
            "command": "uvx",
            "args": [
                "--with", "mcp<2",
                "--with", "requests",
                "phone-mcp"
            ]
        }
    }
}

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

{
    "mcpServers": {
        "phone-mcp": {
            "command": "/absolute/path/to/.venv/bin/python",
            "args": [
                "-m",
                "phone_mcp"
            ]
        }
    }
}

重要：请使用安装了 phone-mcp 的虚拟环境中 Python 的绝对路径，而不是系统 Python。在 Linux/macOS 上，此路径为 /absolute/path/to/.venv/bin/python；在 Windows 上，使用 C:\path\to\.venv\Scripts\python.exe（在 JSON 中将反斜杠转义为 \\）。启动 AI 助手前无需激活环境。

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

用法：

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

  Please call contact hao
  

⚠️ 使用前，请确保：

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

🎯 主要功能

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

🛠️ 要求

• Python 3.10+
• 已启用 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 <action> [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
   

2. 按包名（两种方法）：

   # 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
   

3. 按包名和活动（最可靠的方法）：

   # 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. 自动保存联系人

基于屏幕的自动化

统一的屏幕交互界面让智能 Agent 能够轻松地：

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
   

2. 等待特定元素出现：

   # 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"
   

3. 监控元素消失：

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

4. 获取详细的 UI 变化报告：

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

提示：UI 监控对于自动化脚本尤其有用，可用于等待加载屏幕完成，或确认操作已在 UI 中生效。

📚 详细文档

如需查看完整文档和配置详情，请访问我们的 GitHub 仓库。

🧰 工具文档

屏幕接口 API

此插件提供强大的屏幕接口，包含用于与设备交互的全面 API。以下是主要函数及其参数：

interact_with_screen

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

• 参数：
  • action：操作类型（"tap"、"swipe"、"key"、"text"、"find"、"wait"、"scroll"）
  • 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})

analyze_screen

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_activity

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 模块中

launch_intent

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：Intent 的 MIME 类型（可选）
  • extras：要随 Intent 传递的额外数据（可选）
• **返回值：**包含操作结果的 JSON 字符串
• **位置：**此函数位于 apps.py 模块中

📄 许可证

Apache License，Version 2.0

联系人创建工具

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

前提条件

• Python 3.x
• 已安装并配置 ADB（Android Debug Bridge）
• 已连接 Android 设备，并已授权使用 ADB

用法

基本用法

直接运行脚本：

python create_contact.py

这将使用默认值创建联系人：

• 账户名称："你的账户名"
• 账户类型："com.google"

高级用法

你可以使用 JSON 字符串提供自定义账户名称和类型：

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

输出

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

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

成功输出示例：

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

错误处理

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

注意事项

• 确保 Android 设备已连接，并已获准使用 ADB
• 运行命令时，设备屏幕应处于解锁状态
• 某些设备可能需要额外权限才能修改联系人

应用与快捷方式

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