Phone

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

GitHub
246
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

Usa Python 3.10+ y uv para ejecutar en un entorno aislado:

uvx --with "mcp<2" --with requests phone-mcp

Las dependencias adicionales mantienen la compatibilidad de las versiones existentes de PyPI con la API de MCP v1 y proporcionan requests, que el módulo de mapas importa. Están declaradas en el paquete fuente actualizado, pero se necesitan para versiones anteriores.

Para una instalación persistente con uv:

uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python phone-mcp "mcp<2" requests
.venv/bin/phone-cli --help

O usa el entorno virtual integrado de Python y pip en Linux/macOS:

python3 -m venv .venv
.venv/bin/python -m pip install phone-mcp "mcp<2" requests
.venv/bin/phone-cli --help

En Windows, crea el entorno con py -3 -m venv .venv, luego usa .venv\Scripts\python.exe y .venv\Scripts\phone-cli.exe en lugar de las rutas .venv/bin/ anteriores.

En Debian/Ubuntu, un error de externally-managed-environment significa que el Python del sistema está gestionado por el sistema operativo. Usa uvx o un entorno virtual; no lo omitas con sudo pip o --break-system-packages. Si venv no está disponible, instala python3-venv con el gestor de paquetes de tu sistema primero.

🔧 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": [
                "--with", "mcp<2",
                "--with", "requests",
                "phone-mcp"
            ]
        }
    }
}

Alternativamente, si instalaste con pip:

{
    "mcpServers": {
        "phone-mcp": {
            "command": "/absolute/path/to/.venv/bin/python",
            "args": [
                "-m",
                "phone_mcp"
            ]
        }
    }
}

Importante: Usa la ruta absoluta a Python dentro del entorno virtual donde instalaste phone-mcp, no el Python del sistema. En Linux/macOS esto es /absolute/path/to/.venv/bin/python; en Windows usa C:\path\to\.venv\Scripts\python.exe (escapa las barras invertidas como \\ en JSON). No necesitas activar el entorno antes de lanzar tu asistente de IA.

Nota: Para Cursor, coloca esta configuración en ~/.cursor/mcp.json

Uso:

  • Usa comandos directamente en la conversación de 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 de interfaz automatizada
  • 📸 Multimedia: Capturas de pantalla, grabación de pantalla, control multimedia
  • 📱 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 de Interfaz: Tocar, deslizar, escribir texto, presionar teclas
  • 🔍 Inspección de Interfaz: Encontrar elementos por texto, ID, clase o descripción
  • 🤖 Automatización de Interfaz: Esperar elementos, desplazarse para encontrar elementos
  • 🧠 Análisis de Pantalla: Información estructurada de pantalla e interacción unificada
  • 🌐 Navegador Web: Abrir URLs en el navegador predeterminado del dispositivo
  • 🔄 Monitoreo de Interfaz: Monitorear cambios en la interfaz y esperar que elementos específicos aparezcan o desaparezcan

🛠️ Requisitos

  • Python 3.10+
  • 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 Interfaz

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

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

Este comando:

  1. Abrirá la aplicación de contactos
  2. Navegará a la interfaz de creación de contactos
  3. Completará los campos de nombre y número de teléfono
  4. Guardará el contacto automáticamente

Automatización Basada en Pantalla

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

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

Monitoreo y Automatización de Interfaz

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

  1. Monitoreo básico de 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 interfaz es especialmente útil para scripts de automatización para esperar que las pantallas de carga se completen o confirmar 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 presentan 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 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 captura de pantalla codificada en base64 en el resultado
    • max_elements: Número máximo de elementos de interfaz a procesar
  • Devuelve: Cadena JSON con análisis detallado de 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 automatización de 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 y tipo de cuenta 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 mensaje de salida o 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 será capturado y devuelto 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 pueden requerir permisos adicionales para modificar contactos

Aplicaciones y Accesos Directos

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