📱 Плагин 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"