Phone

Controla tu teléfono Android usando comandos ADB. Requiere herramientas ADB y un dispositivo Android con depuración USB habilitada.

GitHub
244
Prueba este MCPPatrocinado

Documentación

📱 Complemento MCP de Phone

Downloads

🌟 Un potente complemento MCP que te permite controlar tu teléfono Android con facilidad mediante comandos ADB.

Ejemplo

  • Basado en el clima de hoy según el navegador, selecciona y reproduce automáticamente música de netease, sin necesidad de confirmación play_mucic_x2

  • Llama a Hao desde los contactos. Si no contesta, envía un mensaje de texto diciéndole que venga a la Sala de Reuniones 101. call_sms_x2

Documentación en chino

⚡ 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

Configúralo 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. Debes modificarla según la ubicación real de instalación de Python en tu sistema. Así puedes encontrar la ruta de Python en diferentes sistemas operativos:

Linux/macOS: Ejecuta el siguiente comando en la terminal:

which python3

o

which python

Windows: Ejecuta en el Símbolo del sistema (CMD):

where python

O en PowerShell:

(Get-Command python).Path

Asegúrate 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 Cursor, coloca esta configuración en ~/.cursor/mcp.json

Uso:

  • Usa comandos directamente en la conversación con Claude, por ejemplo: 
    Please call contact hao

⚠️ Antes de usar, asegúrate de:

  • ADB esté correctamente instalado y configurado
  • La depuración USB esté habilitada en tu dispositivo Android
  • El dispositivo esté conectado a la computadora mediante USB

🎯 Características Principales

  • 📞 Funciones de llamada: Hacer llamadas, finalizar llamadas, recibir llamadas entrantes
  • 💬 Mensajería: Enviar y recibir SMS, obtener mensajes sin procesar
  • 👥 Contactos: Acceder a los contactos del teléfono, crear nuevos contactos con interacción automatizada de la interfaz de usuario
  • 📸 Multimedia: Capturas de pantalla, grabación de pantalla, control de medios
  • 📱 Aplicaciones: Iniciar aplicaciones, iniciar actividades específicas con intents, listar aplicaciones instaladas, finalizar aplicaciones
  • 🔧 Sistema: Información de ventanas, accesos directos de aplicaciones
  • 🗺️ Mapas: Buscar POIs con números de teléfono
  • 🖱️ Interacción con la interfaz: Tocar, deslizar, escribir texto, presionar teclas
  • 🔍 Inspección de la interfaz: Encontrar elementos por texto, ID, clase o descripción
  • 🤖 Automatización de la interfaz: Esperar elementos, desplazarse para encontrar elementos
  • 🧠 Análisis de pantalla: Información estructurada de la pantalla e interacción unificada
  • 🌐 Navegador web: Abrir URLs en el navegador predeterminado del dispositivo
  • 🔄 Monitoreo de la interfaz: Monitorear cambios en la interfaz y esperar que aparezcan o desaparezcan elementos específicos

🛠️ Requisitos

  • Python 3.7+
  • Dispositivo Android con depuración USB habilitada
  • Herramientas ADB

📋 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"

Multimedia 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 de Pantalla e Interacción

# 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

Inicio de Aplicaciones y Actividades

El complemento proporciona múltiples formas de iniciar aplicaciones y actividades:

  1. Por nombre de 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

  2. 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

  3. 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 encuentras problemas con los comandos app o open_app, usa siempre el comando launch con el nombre completo del componente (paquete/actividad) para la operación más confiable.

Creación de Contactos con Automatización de la Interfaz

El complemento proporciona una forma de crear contactos mediante la interacción con la interfaz:

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

Este comando:

  1. Abre la aplicación de contactos
  2. Navega a la interfaz de creación de contactos
  3. Completa los campos de nombre y número de teléfono
  4. Guarda el contacto automáticamente

Automatización Basada en Pantalla

La interfaz unificada de interacción con la pantalla permite a los agentes inteligentes:

  1. Analizar pantallas: Obtener análisis estructurado de elementos de la interfaz y texto
  2. Tomar decisiones: Basado en patrones de interfaz detectados y acciones disponibles
  3. Ejecutar interacciones: Mediante un sistema de parámetros consistente

Monitoreo y Automatización de la Interfaz

El complemento proporciona potentes capacidades de monitoreo de la interfaz para detectar cambios:

  1. Monitoreo básico de la interfaz:

    # Monitor any UI changes with custom interval (seconds)
phone-cli monitor-ui --interval 0.5 --duration 30

  2. Esperar 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"

  3. Monitorear la desaparición de elementos:

    # Wait for text to disappear
phone-cli monitor-ui --watch-for text_disappears --text "Loading..."

  4. Obtener informes detallados de cambios en la interfaz:

    # Get raw JSON data with all UI change information
phone-cli monitor-ui --raw

Consejo: El monitoreo de la interfaz 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.

📚 Documentación Detallada

Para documentación completa y detalles de configuración, visita nuestro repositorio de GitHub.

🧰 Documentación de Herramientas

API de Interfaz de Pantalla

El complemento proporciona una potente interfaz de pantalla con APIs completas para interactuar con el dispositivo. A continuación se muestran las funciones clave y sus parámetros:

interact_with_screen

async def interact_with_screen(action: str, params: Dict[str, Any] = None) -> str:
    """Execute screen interaction actions"""
  • Parámetros:
    • action: Tipo de acción ("tap", "swipe", "key", "text", "find", "wait", "scroll")
    • 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})

analyze_screen

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 la captura de pantalla codificada en base64 en el resultado
    • max_elements: Número máximo de elementos de la interfaz a procesar
  • Devuelve: Cadena JSON con análisis detallado de la pantalla

create_contact

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 contacto
    • phone: 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 para crear contactos

launch_app_activity

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 a 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'

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"""
  • Parámetros:
    • intent_action: La acción a realizar
    • intent_type: El tipo MIME para el intent (opcional)
    • extras: Datos adicionales para pasar con el intent (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

Herramienta de Creación de Contactos

Esta herramienta proporciona una forma sencilla de crear contactos en un dispositivo Android usando ADB.

Requisitos Previos

  • Python 3.x
  • ADB (Android Debug Bridge) instalado y configurado
  • Dispositivo Android conectado y autorizado para ADB

Uso

Uso Básico

Simplemente ejecuta el script:

python create_contact.py

Esto creará un contacto con valores predeterminados:

  • Nombre de cuenta: "你的账户名"
  • Tipo de cuenta: "com.google"

Uso Avanzado

Puedes proporcionar un nombre de cuenta y tipo personalizados usando una cadena JSON:

python create_contact.py '{"account_name": "your_account", "account_type": "com.google"}'

Salida

El script genera un objeto JSON con:

  • success: booleano que indica si la operación fue exitosa
  • message: 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
  • La entrada JSON no válida resultará en un mensaje de error
  • Cualquier error de comando ADB se capturará y devolverá en el campo de mensaje

Notas

  • Asegúrate de que tu dispositivo Android esté conectado y autorizado para uso de ADB
  • La pantalla del dispositivo debe estar desbloqueada al ejecutar el comando
  • Algunos dispositivos podrían requerir permisos adicionales para modificar contactos

Aplicaciones y Accesos Directos

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