📱 电话 MCP 插件

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

例子

浏览器根据当日天气，自动选择播放网易云音乐，无需确认
从通讯录里给郝打电话。如果他没接，就发短信让他来101会议室。

中文詳細

Related MCP server: PhonePi MCP

⚡ 快速入门

📥 安装

# 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 ：在终端中运行以下命令：
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 对话中直接使用命令，例如：
Please call contact hao

⚠️ 使用前，请确保：

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

用法

基本用法

只需运行脚本：

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
运行该命令时，设备屏幕应处于解锁状态
某些设备可能需要额外的权限才能修改联系人

应用程序和快捷方式

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