📱 Complemento MCP de teléfono
🌟 Un poderoso complemento MCP que te permite controlar tu teléfono Android con facilidad a través de comandos ADB.
Ejemplo
- Según el clima de hoy del navegador, selecciona y reproduce automáticamente música de NetEase, sin necesidad de confirmación
- Llama a Hao desde la lista de contactos. Si no contesta, envíale un SMS diciéndole que vaya a la Sala de Reuniones 101.
Lengua china
⚡ Inicio rápido
📥 Instalación
# 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
🔧 Configuración
Configuración del asistente de IA
Configura en la configuración de tu asistente de IA (Cursor, Trae, Claude, etc.):
{
"mcpServers": {
"phone-mcp": {
"command": "uvx",
"args": [
"phone-mcp"
]
}
}
}
Alternativamente, si lo instalaste con pip:
{
"mcpServers": {
"phone-mcp": {
"command": "/usr/local/bin/python",
"args": [
"-m",
"phone_mcp"
]
}
}
}
Importante : La ruta /usr/local/bin/python en la configuración anterior es la ruta al intérprete de Python. Debe modificarla según la ubicación de instalación de Python en su sistema. A continuación, se explica cómo encontrar la ruta de Python en diferentes sistemas operativos:
Linux/macOS : Ejecute el siguiente comando en la terminal:
o
Windows : Ejecutar en el símbolo del sistema (CMD):
O en PowerShell:
(Get-Command python).Path
Asegúrese de reemplazar /usr/local/bin/python en la configuración con la ruta completa, por ejemplo en Windows podría ser C:\Python39\python.exe
Nota : Para el cursor, coloque esta configuración en ~/.cursor/mcp.json
Uso:
- Utilice comandos directamente en la conversación de Claude, por ejemplo:
⚠️ Antes de usar, asegúrese de:
- ADB está correctamente instalado y configurado
- La depuración USB está habilitada en su dispositivo Android
- El dispositivo está conectado a la computadora a través de USB
🎯 Características principales
- 📞 Funciones de llamada : Realizar llamadas, finalizar llamadas, recibir llamadas entrantes
- 💬 Mensajería : Envía y recibe SMS, recibe mensajes sin procesar
- 👥 Contactos : acceda a los contactos del teléfono, cree nuevos contactos con interacción de interfaz de usuario automatizada
- 📸 Medios : Capturas de pantalla, grabación de pantalla, control de medios
- 📱 Aplicaciones : Iniciar aplicaciones, iniciar actividades específicas con intenciones, enumerar aplicaciones instaladas, finalizar aplicaciones
- 🔧 Sistema : Información de la ventana, accesos directos a aplicaciones
- 🗺️ Mapas : Busca puntos de interés con números de teléfono
- 🖱️ Interacción de la interfaz de usuario : toque, deslice, escriba texto, presione teclas
- 🔍 Inspección de UI : busque elementos por texto, ID, clase o descripción
- 🤖 Automatización de UI : esperar elementos, desplazarse para encontrarlos
- 🧠 Análisis de pantalla : información de pantalla estructurada e interacción unificada
- 🌐 Navegador web : abre URL en el navegador predeterminado del dispositivo
- 🔄 Monitoreo de la interfaz de usuario : monitoree los cambios de la interfaz de usuario y espere a que aparezcan o desaparezcan elementos específicos
🛠️ Requisitos
- Python 3.7+
- Dispositivo Android con depuración USB habilitada
- Herramientas del BAD
📋 Comandos básicos
Dispositivo y conexión
# Check device connection
phone-cli check
# Get screen size
phone-cli screen-interact find method=clickable
Comunicación
# 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"
Medios y aplicaciones
# 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
Análisis e interacción de pantalla
# 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
Ubicación y mapas
# Search nearby POIs with phone numbers
phone-cli get-poi 116.480053,39.987005 --keywords restaurant --radius 1000
📚 Uso avanzado
Lanzamiento de la aplicación y la actividad
El complemento proporciona múltiples formas de iniciar aplicaciones y actividades:
- Por nombre de la aplicación (dos métodos):
# 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
- Por nombre de paquete (dos métodos):
# 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
- Por paquete y actividad (método más confiable):
# This method works on all devices
phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity
Nota : Si encuentra problemas con la app o los comandos open_app , utilice siempre el comando launch con el nombre completo del componente (paquete/actividad) para obtener una operación más confiable.
El complemento proporciona una forma de crear contactos a través de la interacción de la interfaz de usuario:
# Create a new contact with UI automation
phone-cli create-contact "John Doe" "1234567890"
Este comando hará lo siguiente:
- Abra la aplicación de contactos
- Navegue a la interfaz de creación de contactos.
- Complete los campos de nombre y número de teléfono
- Guardar el contacto automáticamente
Automatización basada en pantalla
La interfaz de interacción de pantalla unificada permite a los agentes inteligentes:
- Analizar pantallas : obtenga un análisis estructurado de los elementos de la interfaz de usuario y el texto
- Tomar decisiones : según los patrones de IU detectados y las acciones disponibles
- Ejecutar interacciones : A través de un sistema de parámetros consistente
Monitoreo y automatización de la interfaz de usuario
El complemento proporciona potentes capacidades de monitoreo de UI para detectar cambios en la interfaz:
- Monitoreo básico de UI :
# Monitor any UI changes with custom interval (seconds)
phone-cli monitor-ui --interval 0.5 --duration 30
- Espere a que aparezcan elementos específicos :
# 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"
- Elementos del monitor que desaparecen :
# Wait for text to disappear
phone-cli monitor-ui --watch-for text_disappears --text "Loading..."
- Obtenga informes detallados de cambios de UI :
# Get raw JSON data with all UI change information
phone-cli monitor-ui --raw
Consejo : La supervisión de la interfaz de usuario es especialmente útil para que los scripts de automatización esperen a que se completen las pantallas de carga o confirmen que las acciones han tenido efecto en la interfaz de usuario.
📚 Documentación detallada
Para obtener la documentación completa y los detalles de configuración, visita nuestro repositorio de GitHub .
🧰 Documentación de la herramienta
API de interfaz de pantalla
El complemento proporciona una potente interfaz de pantalla con API completas para interactuar con el dispositivo. A continuación, se muestran las funciones clave y sus parámetros:
interactuar_con_la_pantalla
async def interact_with_screen(action: str, params: Dict[str, Any] = None) -> str:
"""Execute screen interaction actions"""
- Parámetros:
action : Tipo de acción ("pulsar", "deslizar", "tecla", "texto", "buscar", "esperar", "desplazarse")params : Diccionario con parámetros específicos para cada tipo de acción
- Devuelve: cadena JSON con los resultados de la operación
Ejemplos:
# 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})
analizar_pantalla
async def analyze_screen(include_screenshot: bool = False, max_elements: int = 50) -> str:
"""Analyze the current screen and provide structured information about UI elements"""
- Parámetros:
include_screenshot : Si se debe incluir una captura de pantalla codificada en base64 en el resultadomax_elements : Número máximo de elementos de UI a procesar
- Devuelve: cadena JSON con análisis de pantalla detallado
async def create_contact(name: str, phone: str) -> str:
"""Create a new contact with the given name and phone number"""
- Parámetros:
name : El nombre completo del contactophone : El número de teléfono del contacto
- Devuelve: cadena JSON con el resultado de la operación
- Ubicación: Esta función se encuentra en el módulo 'contacts.py' e implementa la automatización de la interfaz de usuario para crear contactos
actividad de lanzamiento de la aplicación
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"""
- Parámetros:
package_name : El nombre del paquete de la aplicación que se iniciaráactivity_name : La actividad específica a iniciar (opcional)
- Devuelve: cadena JSON con el resultado de la operación
- Ubicación: Esta función se encuentra en el módulo 'apps.py'
intención de lanzamiento
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"""
- Parámetros:
intent_action : La acción a realizarintent_type : el tipo MIME para la intención (opcional)extras : Datos adicionales para pasar con la intención (opcional)
- Devuelve: cadena JSON con el resultado de la operación
- Ubicación: Esta función se encuentra en el módulo 'apps.py'
📄 Licencia
Licencia Apache, versión 2.0
Esta herramienta proporciona una forma sencilla de crear contactos en un dispositivo Android usando ADB.
Prerrequisitos
- Python 3.x
- ADB (Android Debug Bridge) instalado y configurado
- Dispositivo Android conectado y autorizado para ADB
Uso
Uso básico
Simplemente ejecute el script:
Esto creará un contacto con valores predeterminados:
- Nombre de cuenta: "你的账户名"
- Tipo de cuenta: "com.google"
Uso avanzado
Puede proporcionar un nombre y tipo de cuenta personalizados mediante una cadena JSON:
python create_contact.py '{"account_name": "your_account", "account_type": "com.google"}'
Producción
El script genera un objeto JSON con:
success : booleano que indica si la operación fue exitosamessage : cualquier salida o mensaje de error del comando
Ejemplo de salida exitosa:
{"success": true, "message": ""}
Manejo de errores
- Si ADB no está disponible o el dispositivo no está conectado, el script devolverá un error
- Una entrada JSON no válida generará un mensaje de error
- Cualquier error del comando ADB se capturará y se devolverá en el campo de mensaje.
Notas
- Asegúrese de que su dispositivo Android esté conectado y autorizado para el uso de ADB
- La pantalla del dispositivo debe estar desbloqueada al ejecutar el comando
- Algunos dispositivos pueden requerir permisos adicionales para modificar los contactos.
Aplicaciones y accesos directos
# Get app shortcuts (with pagination)
phone-cli shortcuts --package "com.example.app"