Skip to main content
Glama
deenesjakoruzh
hao-cyber

Phone MCP Plugin

by hao-cyber
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

📱 电话 MCP 插件

下载

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

例子

  • 浏览器根据当日天气，自动选择播放网易云音乐，无需确认播放_mucic_x2

  • 从通讯录里给郝打电话。如果他没接，就发短信让他来101会议室。 呼叫短信

中文詳細

Related MCP server: ADB MCP Server

⚡ 快速入门

📥 安装

# 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

📚 高级用法

应用程序和活动启动

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

  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命令时遇到问题，请始终使用带有完整组件名称（package/activity）的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

  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，用于与设备交互。以下是主要功能及其参数：

与屏幕交互

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"

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers