📱 电话 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 ：在终端中运行以下命令：
或者
Windows ：在命令提示符（CMD）中运行：
或者在 PowerShell 中：
(Get-Command python).Path
确保将配置中的/usr/local/bin/python替换为完整路径，例如在 Windows 上它可能是C:\Python39\python.exe
注意：对于 Cursor，请将此配置放在~/.cursor/mcp.json中
用法：
⚠️ 使用前，请确保：
- ADB 已正确安装和配置
- 您的 Android 设备上已启用 USB 调试
- 设备通过 USB 连接到计算机
🎯 主要特点
- 📞通话功能：拨打电话、结束通话、接听来电
- 💬消息传递：发送和接收短信，获取原始消息
- 👥联系人：访问手机联系人，通过自动化 UI 交互创建新联系人
- 📸媒体：截图、屏幕录制、媒体控制
- 📱应用程序：启动应用程序、启动具有意图的特定活动、列出已安装的应用程序、终止应用程序
- 🔧系统：窗口信息、应用程序快捷方式
- 🗺️地图：通过电话号码搜索兴趣点
- 🖱️ 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 <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
📚 高级用法
应用程序和活动启动
该插件提供了多种启动应用程序和活动的方式：
- 按应用名称（两种方法）：
# 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
- 按包名称（两种方法）：
# 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
- 按包装和活动（最可靠的方法）：
# This method works on all devices
phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity
注意：如果您在使用app或open_app命令时遇到问题，请始终使用带有完整组件名称（package/activity）的launch命令，以实现最可靠的操作。
使用 UI 自动化创建联系人
该插件提供了通过UI交互创建联系人的方法：
# Create a new contact with UI automation
phone-cli create-contact "John Doe" "1234567890"
此命令将：
- 打开联系人应用
- 导航至联系人创建界面
- 填写姓名和电话号码字段
- 自动保存联系人
基于屏幕的自动化
统一的屏幕交互界面，让智能座席能够轻松：
- 分析屏幕：获取 UI 元素和文本的结构化分析
- 做出决策：基于检测到的 UI 模式和可用的操作
- 执行交互：通过一致的参数系统
UI监控和自动化
该插件提供了强大的UI监控功能，可以检测界面变化：
- 基本 UI 监控：
# Monitor any UI changes with custom interval (seconds)
phone-cli monitor-ui --interval 0.5 --duration 30
- 等待特定元素出现：
# 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"
- 监视元素消失：
# Wait for text to disappear
phone-cli monitor-ui --watch-for text_disappears --text "Loading..."
- 获取详细的 UI 更改报告：
# Get raw JSON data with all UI change information
phone-cli monitor-ui --raw
提示：UI 监控对于自动化脚本特别有用，可以等待加载屏幕完成或确认操作已在 UI 中生效。
📚 详细文档
如需完整的文档和配置详细信息，请访问我们的GitHub 存储库。
🧰 工具文档
屏幕接口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 字符串
创建联系人
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 自动化来创建联系人
启动应用活动
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 ：通过 Intent 传递的额外数据（可选）
- **返回：**操作结果的 JSON 字符串
- **位置：**该函数位于“apps.py”模块中
📄 许可证
Apache 许可证，版本 2.0
联系人创建工具
该工具提供了一种使用 ADB 在 Android 设备上创建联系人的简单方法。
先决条件
- Python 3.x
- ADB（Android Debug Bridge）安装和配置
- Android 设备已连接并授权 ADB
用法
基本用法
只需运行脚本：
这将创建一个具有默认值的联系人：
- 账户名：“您的账户名”
- 帐户类型：“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
- 运行该命令时，设备屏幕应处于解锁状态
- 某些设备可能需要额外的权限才能修改联系人
应用程序和快捷方式
# Get app shortcuts (with pagination)
phone-cli shortcuts --package "com.example.app"