📱 Complemento MCP de teléfono

Descargas

🌟 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

Related MCP server: PhonePi MCP

⚡ 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:
which python3
o
which python
Windows : Ejecutar en el símbolo del sistema (CMD):
where python
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:
```
Please call contact hao
```

⚠️ 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.

Creación de contactos con automatización de UI

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 resultado
- max_elements : Número máximo de elementos de UI a procesar
Devuelve: cadena JSON con análisis de pantalla detallado

crear_contacto

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 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 realizar
- intent_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

Herramienta de creación de contactos

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:

python create_contact.py

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