📱 Плагин MCP для телефона

Загрузки

🌟 Мощный плагин MCP, позволяющий вам легко управлять вашим телефоном Android с помощью команд ADB.

Пример

На основе текущей погоды через браузер, автоматически выбирает и воспроизводит музыку Netease, подтверждение не требуется
Позвоните Хао из контактов. Если он не ответит, отправьте ему текстовое сообщение с просьбой прийти в комнату для совещаний 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

🔧 Конфигурация

Конфигурация помощника ИИ

Настройте конфигурацию вашего помощника ИИ (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/mcp.json

Использование:

Используйте команды непосредственно в разговоре с Клодом, например:
```
Please call contact hao
```

⚠️ Перед использованием убедитесь:

ADB правильно установлен и настроен
На вашем Android-устройстве включена отладка по USB.
Устройство подключено к компьютеру через USB

🎯 Основные характеристики

📞 Функции вызова : совершать звонки, завершать звонки, принимать входящие звонки
💬 Сообщения : отправка и получение SMS, получение необработанных сообщений
👥 Контакты : доступ к контактам телефона, создание новых контактов с помощью автоматизированного взаимодействия с пользовательским интерфейсом.
📸 Медиа : скриншоты, запись экрана, управление медиа
📱 Приложения : запуск приложений, запуск определенных действий с намерениями, вывод списка установленных приложений, завершение работы приложений
🔧 Система : информация об окнах, ярлыки приложений
🗺️ Карты : Поиск точек интереса по номерам телефонов
🖱️ Взаимодействие с пользовательским интерфейсом : нажатие, смахивание, ввод текста, нажатие клавиш
🔍 Проверка пользовательского интерфейса : поиск элементов по тексту, идентификатору, классу или описанию
🤖 Автоматизация пользовательского интерфейса : ожидание элементов, прокрутка для поиска элементов
🧠 Анализ экрана : структурированная информация на экране и единое взаимодействие
🌐 Веб-браузер : открытие URL-адресов в браузере устройства по умолчанию.
🔄 Мониторинг пользовательского интерфейса : отслеживайте изменения пользовательского интерфейса и ждите появления или исчезновения определенных элементов.

🛠️ Требования

Питон 3.7+
Устройство Android с включенной отладкой по USB
Инструменты АБР

📋 Основные команды

Устройство и подключение

# 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 , всегда используйте команду launch с полным именем компонента (пакет/активность) для наиболее надежной работы.

Создание контактов с помощью автоматизации пользовательского интерфейса

Плагин предоставляет возможность создания контактов посредством взаимодействия с пользовательским интерфейсом:

# Create a new contact with UI automation
phone-cli create-contact "John Doe" "1234567890"

Эта команда:

Откройте приложение «Контакты».
Перейдите в интерфейс создания контакта.
Заполните поля имени и номера телефона
Сохраните контакт автоматически

Автоматизация на основе экрана

Унифицированный интерфейс взаимодействия с экраном позволяет интеллектуальным агентам легко:

Анализ экранов : получите структурированный анализ элементов пользовательского интерфейса и текста.
Принимать решения : на основе обнаруженных шаблонов пользовательского интерфейса и доступных действий.
Осуществление взаимодействий : через последовательную систему параметров

Мониторинг и автоматизация пользовательского интерфейса

Плагин предоставляет мощные возможности мониторинга пользовательского интерфейса для обнаружения изменений интерфейса:

Базовый мониторинг пользовательского интерфейса :

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

Получите подробные отчеты об изменениях пользовательского интерфейса :
```
# Get raw JSON data with all UI change information
phone-cli monitor-ui --raw
```

Совет : мониторинг пользовательского интерфейса особенно полезен для сценариев автоматизации, позволяющих дождаться завершения загрузки экранов или подтвердить, что действия вступили в силу в пользовательском интерфейсе.

📚 Подробная документация

Полную документацию и сведения о конфигурации можно найти в нашем репозитории 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 : Максимальное количество элементов пользовательского интерфейса для обработки.
Возвращает: строку 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» и реализует автоматизацию пользовательского интерфейса для создания контактов.

запуск_приложения_активность

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 : тип MIME для намерения (необязательно)
- extras : Дополнительные данные для передачи с намерением (необязательно)
Возвращает: строку JSON с результатом операции.
Расположение: эта функция находится в модуле «apps.py».

📄 Лицензия

Лицензия Apache, версия 2.0

Инструмент создания контактов

Этот инструмент предоставляет простой способ создания контактов на устройстве Android с помощью ADB.

Предпосылки

Питон 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"