技术文档摘要

📱 Phone MCP 插件

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

示例

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

• 拨打联系人Hao。如果他不接电话，则发送一条短信告诉他到101会议室。

中文文档

⚡ 快速开始

📥 安装

# 直接使用uvx运行（推荐，uv的一部分，不需要单独安装）
uvx phone-mcp

# 或者使用uv安装
uv pip install phone-mcp

# 或者使用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： 在终端中运行以下命令：

which python3

或

which python

Windows： 在命令提示符(CMD)中运行：

where python

或在PowerShell中运行：

(Get-Command python).Path

确保用完整的路径替换配置中的/usr/local/bin/python，例如在Windows中可能是C:\Python39\python.exe

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

使用方法：

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

  请拨打联系人Hao
  

⚠️ 使用前确保：

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

🎯 主要功能

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

🛠️ 要求

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

📋 基本命令

设备及连接

# 检查设备连接
phone-cli check

# 获取屏幕大小
phone-cli screen-interact find method=clickable

通信

# 拨打电话
phone-cli call 1234567890

# 结束当前通话
phone-cli hangup

# 发送短信
phone-cli send-sms 1234567890 "你好"

# 获取收到的消息（带分页）
phone-cli messages --limit 10

# 获取发送的消息（带分页）
phone-cli sent-messages --limit 10

# 获取联系人（带分页）
phone-cli contacts --limit 20

# 通过UI自动化创建新联系人
phone-cli create-contact "John Doe" "1234567890"

媒体及应用

# 截屏
phone-cli screenshot

# 录屏
phone-cli record --duration 30

# 启动应用（可能在所有设备上都不工作）
phone-cli app camera

# 使用open_app替代方法启动应用（如果app命令不工作）
phone-cli open_app camera

# 关闭应用
phone-cli close-app com.android.camera

# 列出已安装的应用（基本信息，更快）
phone-cli list-apps

# 分页列出应用
phone-cli list-apps --page 1 --page-size 10

# 详细列出应用（更慢）
phone-cli list-apps --detailed

# 启动特定活动（适用于所有设备的可靠方法）
phone-cli launch com.android.settings/.Settings

# 通过包名启动应用（可能在所有设备上都不工作）
phone-cli app com.android.contacts

# 使用open_app替代方法通过包名启动应用（如果app命令不工作）
phone-cli open_app com.android.contacts

# 通过包名和活动启动应用（最可靠的方法）
phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity

# 在默认浏览器中打开URL
phone-cli open-url google.com

屏幕分析及交互

# 分析当前屏幕，获取结构化信息
phone-cli analyze-screen

# 统一交互界面
phone-cli screen-interact <action> [参数]

# 点击坐标
phone-cli screen-interact tap x=500 y=800

# 通过文本点击元素
phone-cli screen-interact tap element_text="登录"

# 通过内容描述点击元素
phone-cli screen-interact tap element_content_desc="日历"

# 滑动手势（向下滚动）
phone-cli screen-interact swipe x1=500 y1=1000 x2=500 y2=200 duration=300

# 按键
phone-cli screen-interact key keycode=back

# 输入文本
phone-cli screen-interact text content="Hello World"

# 查找元素
phone-cli screen-interact find method=text value="登录" partial=true

# 等待元素
phone-cli screen-interact wait method=text value="成功" timeout=10

# 滚动查找元素
phone-cli screen-interact scroll method=text value="设置" direction=down max_swipes=5

# 监控UI变化
phone-cli monitor-ui --interval 0.5 --duration 30

# 监控直到特定文本出现
phone-cli monitor-ui --watch-for text_appears --text "欢迎"

# 监控直到特定元素ID出现
phone-cli monitor-ui --watch-for id_appears --id "login_button"

# 监控直到特定元素类出现
phone-cli monitor-ui --watch-for class_appears --class-name "android.widget.Button"

# 以原始JSON形式输出UI变化
phone-cli monitor-ui --raw

地理位置及地图

# 搜索附近带有电话号码的POI
phone-cli get-poi 116.480053,39.987005 --keywords 餐厅 --radius 1000

📚 高级用法

应用及活动启动

插件提供了多种启动应用和活动的方式：

1. 通过应用名称（两种方法）：

   # 方法1：使用app命令（可能在所有设备上都不工作）
   phone-cli app camera
   
   # 方法2：使用open_app命令（如果app命令失败的替代方法）
   phone-cli open_app camera
   

2. 通过包名（两种方法）：

   # 方法1：使用app命令（可能在所有设备上都不工作）
   phone-cli app com.android.contacts
   
   # 方法2：使用open_app命令（如果app命令失败的替代方法）
   phone-cli open_app com.android.contacts
   

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

   # 这种方法适用于所有设备
   phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity
   

注意：如果遇到app或open_app命令的问题，请始终使用带有完整组件名（包名/活动名）的launch命令进行最可靠的执行。

通过UI自动化创建联系人

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

# 通过UI自动化创建新联系人
phone-cli create-contact "John Doe" "1234567890"

此命令会：

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

基于屏幕的自动化

统一的屏幕交互界面允许智能代理轻松地：

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

UI监控与自动化

插件提供了强大的UI监控能力，用于检测界面变化：

1. 基本UI监控：

   # 监控任何UI变化，自定义间隔（秒）
   phone-cli monitor-ui --interval 0.5 --duration 30
   

2. 等待特定元素出现：

   # 等待文本出现（适用于自动化测试）
   phone-cli monitor-ui --watch-for text_appears --text "登录成功"
   
   # 等待特定ID出现
   phone-cli monitor-ui --watch-for id_appears --id "确认对话框"
   

3. 监控元素消失：

   # 等待文本消失
   phone-cli monitor-ui --watch-for text_disappears --text "加载中..."
   

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

   # 获取包含所有UI变化信息的原始JSON数据
   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:
    """执行屏幕交互动作"""

• 参数：
  • action：动作类型（"tap"、"swipe"、"key"、"text"、"find"、"wait"、"scroll"）
  • params：每个动作类型的特定参数字典
• 返回值：包含操作结果的JSON字符串

示例：

# 点击坐标
result = await interact_with_screen("tap", {"x": 100, "y": 200})

# 通过文本点击元素
result = await interact_with_screen("tap", {"element_text": "登录"})

# 向下滑动
result = await interact_with_screen("swipe", {"x1": 500, "y1": 300, "x2": 500, "y2": 1200, "duration": 300})

# 输入文本
result = await interact_with_screen("text", {"content": "Hello world"})

# 按下返回键
result = await interact_with_screen("key", {"keycode": "back"})

# 通过文本查找元素
result = await interact_with_screen("find", {"method": "text", "value": "设置", "partial": True})

# 等待元素出现
result = await interact_with_screen("wait", {"method": "text", "value": "成功", "timeout": 10, "interval": 0.5})

# 滚动查找元素
result = await interact_with_screen("scroll", {"method": "text", "value": "隐私政策", "direction": "down", "max_swipes": 8})

analyze_screen

async def analyze_screen(include_screenshot: bool = False, max_elements: int = 50) -> str:
    """分析当前屏幕并提供关于UI元素的结构化信息"""

• 参数：
  • include_screenshot：是否在结果中包含base64编码的截图
  • max_elements：处理的最大UI元素数量
• 返回值：包含详细屏幕分析的JSON字符串

create_contact

async def create_contact(name: str, phone: str) -> str:
    """使用给定的姓名和电话号码创建新的联系人"""

• 参数：
  • name：联系人的全名
  • phone：联系人的电话号码
• 返回值：包含操作结果的JSON字符串
• 位置：此函数位于'contacts.py'模块中，并实现了UI自动化以创建联系人

launch_app_activity

async def launch_app_activity(package_name: str, activity_name: Optional[str] = None) -> str:
    """使用包名启动应用，可选地指定活动名"""

• 参数：
  • 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:
    """使用Android意图系统启动活动"""

• 参数：
  • intent_action：要执行的动作
  • intent_type：意图的MIME类型（可选）
  • extras：要传递给意图的额外数据（可选）
• 返回值：包含操作结果的JSON字符串
• 位置：此函数位于'apps.py'模块中

📄 许可证

Apache许可证，第2.0版

联系人创建工具

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

前提条件

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

使用方法

基础用法

只需运行脚本：

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命令错误都将被捕获并在消息字段中返回

注意事项

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

应用及快捷方式

# 获取应用快捷方式（带分页）
phone-cli shortcuts --package "com.example.app"