ERIUS PHONE MCP

erius-phone-mcp

Un servidor MCP que convierte tu dispositivo ERIUS PHONE en herramientas nativas para Claude Code, Claude Desktop, Cursor, o cualquier otro cliente MCP. Un dispositivo ERIUS PHONE es un teléfono o tableta Android real dedicado a tu agente. Una vez que este servidor esté conectado, tu agente puede:

• listar sus dispositivos
• leer la pantalla como un árbol de accesibilidad o una captura de pantalla
• tocar, mantener presionado, escribir, deslizar y desplazarse
• iniciar y detener aplicaciones, abrir URLs y enviar intents
• instalar y desinstalar APKs
• extraer registros de fallos

El agente controla el dispositivo directamente. No necesitas escribir ningún código de conexión.

Acceso anticipado: este paquete es pre-1.0 (0.2.0). Los nombres de las herramientas y los argumentos pueden cambiar antes de la versión 1.0.

Requisitos

• Python 3.10+
• Una clave API de ERIUS PHONE. Regístrate en https://eriusphone.com; consulta "Cómo obtener una clave API" a continuación.

Instalación

Opción A: uvx (sin paso de instalación). Si tienes uv, tu cliente MCP puede iniciar el servidor con uvx erius-phone-mcp. uv descarga el paquete y lo mantiene en su propio entorno. Las configuraciones de cliente a continuación muestran esta forma.

Opción B: pip, en su propio entorno virtual para que sus dependencias no entren en conflicto con tus otros proyectos de Python:

python3 -m venv ~/.venvs/erius-phone-mcp
~/.venvs/erius-phone-mcp/bin/pip install erius-phone-mcp

Esto instala un comando erius-phone-mcp en ~/.venvs/erius-phone-mcp/bin/erius-phone-mcp. Usa esa ruta absoluta como command en la configuración de tu cliente: las aplicaciones GUI como Claude Desktop y Cursor generalmente no ven el PATH de tu venv. python -m erius_phone_mcp hace lo mismo que ejecutar el comando.

Configuración

El servidor se configura completamente a través de variables de entorno:

Variable	Requerida	Qué es
ERIUS_PHONE_API_KEY	sí	Tu clave API de ERIUS PHONE. Cada solicitud se autentica con ella y se limita a tu cuenta.
ERIUS_PHONE_DEFAULT_DEVICE	no	El id del dispositivo a usar cuando una llamada de herramienta no lo especifica (p. ej. vanilla). Sin él, el agente pasa device en cada llamada; list_devices muestra los ids.
ERIUS_PHONE_API_URL	no	URL base de la API. Por defecto https://api.eriusphone.com; solo configúrala si te dimos una diferente.
ERIUS_PHONE_TIMEOUT	no	Tiempo de espera HTTP por solicitud, en segundos. Por defecto 30.

Cómo obtener una clave API

Solicita acceso en https://eriusphone.com. Durante el acceso anticipado, el equipo de ERIUS PHONE configura cada cuenta manualmente. Recibirás tu clave API y los id(s) de dispositivo directamente de nosotros. Si te registraste y no has recibido respuesta, envía un correo a info@eriusphone.com. La misma clave te permite iniciar sesión en el panel de control en https://eriusphone.com/dashboard/, que muestra tus dispositivos en vivo.

Trata la clave como una contraseña: cualquiera que la tenga puede controlar tu dispositivo.

Importante: los clientes MCP inician este servidor como un subproceso, y generalmente no transmiten las variables que export en tu shell. Coloca las variables en el bloque env del cliente, como se muestra a continuación.

Añádelo a tu cliente MCP

En cada ejemplo, reemplaza la clave y el id del dispositivo con los tuyos. Si instalaste con pip en lugar de usar uvx, reemplaza "command": "uvx", "args": ["erius-phone-mcp"] with "command": "/home/you/.venvs/erius-phone-mcp/bin/erius-phone-mcp".

Claude Code

claude mcp add erius-phone \
  -e ERIUS_PHONE_API_KEY=your-api-key \
  -e ERIUS_PHONE_DEFAULT_DEVICE=your-device-id \
  -- uvx erius-phone-mcp

Añade -s user para que el servidor esté disponible en todos tus proyectos, o -s project para escribirlo en un .mcp.json compartido. No comprometas tu clave en un .mcp.json compartido. Claude Code expande las referencias ${VAR} en ese archivo, por lo que puedes mantener la clave en una variable de entorno en su lugar:

{
  "mcpServers": {
    "erius-phone": {
      "command": "uvx",
      "args": ["erius-phone-mcp"],
      "env": {
        "ERIUS_PHONE_API_KEY": "${ERIUS_PHONE_API_KEY}",
        "ERIUS_PHONE_DEFAULT_DEVICE": "your-device-id"
      }
    }
  }
}

Ejecuta /mcp dentro de Claude Code para verificar que erius-phone está conectado.

Claude Desktop

Edita claude_desktop_config.json (Configuración → Desarrollador → Editar Configuración). En macOS está en ~/Library/Application Support/Claude/; en Windows está en %APPDATA%\Claude\.

{
  "mcpServers": {
    "erius-phone": {
      "command": "uvx",
      "args": ["erius-phone-mcp"],
      "env": {
        "ERIUS_PHONE_API_KEY": "your-api-key",
        "ERIUS_PHONE_DEFAULT_DEVICE": "your-device-id"
      }
    }
  }
}

Si Claude Desktop no puede encontrar uvx, coloca su ruta absoluta en command (which uvx). Cierra y vuelve a abrir Claude Desktop por completo después de editar.

Cursor

Coloca el mismo bloque mcpServers en ~/.cursor/mcp.json para usarlo en todos los proyectos, o en .cursor/mcp.json para un solo proyecto. Luego habilita erius-phone en Configuración de Cursor → MCP.

Cualquier otro cliente MCP

El servidor habla MCP a través de stdio. Apunta tu cliente al ejecutable uvx erius-phone-mcp, or at the erius-phone-mcp y pasa las variables de entorno anteriores.

Herramientas

Cada herramienta que actúa sobre un dispositivo acepta un argumento opcional device. Si lo omites, la herramienta usa ERIUS_PHONE_DEFAULT_DEVICE.

Cuenta y dispositivos

Herramienta	Descripción
whoami	Qué cuenta y clave está usando este servidor, y los ids de dispositivo a los que puede acceder. Una forma rápida de verificar que la clave funciona.
list_devices	Cada dispositivo al que tu clave puede acceder, con estado en vivo (iniciado, versión de Android, tamaño de pantalla).
get_device	Estado completo de un dispositivo, incluida la aplicación actualmente en primer plano.

Ver la pantalla

Herramienta	Descripción
snapshot	Instantánea del árbol de accesibilidad de la pantalla actual: cada elemento visible con su texto, rol y un ref que puedes pasar a tocar/escribir/desplazarse. Las referencias se restablecen en cada instantánea.
screenshot	La pantalla como contenido de imagen MCP, para que el modelo la vea directamente. Por defecto: JPEG, lado más largo 1024 px (decenas de KB). format, quality, max_side y scale cambian eso; format="png", max_side=null da el PNG de tamaño completo (aproximadamente 3 MB en un teléfono). Una línea de texto da los tamaños de imagen y pantalla.
foreground	Solo la aplicación en primer plano (paquete, actividad) y si se muestra un diálogo de fallo.
wait_for_text	Espera hasta que aparezca algún texto en pantalla, hasta timeout_ms (máximo 120000). Devuelve la instantánea que vio.

Actuar en la pantalla

Herramienta	Descripción
tap	Tocar por ref, por text/content_desc visible, o en píxeles x,y brutos.
long_press	Mantener presionado por ref, por text/content_desc, o en x,y (tiempo de espera opcional ms).
type_text	Escribir en un campo. Puede tocar un ref/text_target primero, clear el campo y presionar Enter después.
press_key	atrás, inicio, enter, eliminar, tab, escape, arriba, abajo, izquierda, derecha, espacio, encendido, subir volumen, bajar volumen, recientes, menú, despertar, o un código de tecla numérico.
swipe	Deslizar entre dos puntos en píxeles del dispositivo.
scroll	Desplazar un contenedor hacia arriba/abajo/izquierda/derecha. Pasa el ref del ScrollView/Lista en sí, no el de una fila dentro de él.

Aplicaciones

Herramienta	Descripción
launch_app	Iniciar una aplicación instalada por nombre de paquete (p. ej. com.android.settings).
open_url	Abrir una URL http/https/market, opcionalmente en una aplicación específica.
send_intent	Iniciar una actividad con cualquier acción de intent, p. ej. android.settings.WIFI_SETTINGS, con datos, paquete, componente y extras opcionales.
stop_app	Forzar la detención de una aplicación.
list_apps	Aplicaciones instaladas; third_party_only=True solo para las instaladas por el usuario.
install_apk	Subir e instalar un APK desde un archivo en la máquina que ejecuta este servidor. Devuelve el nombre del paquete, la versión y si la instalación fue exitosa.
uninstall_app	Desinstalar una aplicación por nombre de paquete.
get_crash_log	El búfer de registro de fallos del dispositivo (logcat -b crash). Úsalo después de que una aplicación falle para ver el seguimiento de pila real.

Ejemplo rápido

Una vez que el servidor esté conectado, pide a tu agente en lenguaje natural, p. ej. "Lista mis dispositivos ERIUS, ve a la pantalla de inicio y abre Contactos." Esto es lo que sucede internamente. Las salidas a continuación son reales, ligeramente recortadas.

1. Encuentra tu dispositivo. El agente llama a list_devices:

{"devices": [
  {"id": "vanilla", "description": "redroid Android 13, no Google services", "state": "device",
   "bootCompleted": true, "android": "13", "sdk": 33, "screen": {"width": 720, "height": 1280}},
  {"id": "tablet1", "form": "tablet", "description": "redroid Android 13 (vanilla, tablet)", "state": "device",
   "bootCompleted": true, "android": "13", "sdk": 33, "screen": {"width": 1600, "height": 2560}}
]}

2. Ve a inicio y mira la pantalla. press_key(key="home", device="vanilla") devuelve {"ok": true}, luego snapshot(device="vanilla") devuelve la aplicación en primer plano más este árbol:

- Group
  - ScrollView [ref=1]
    - Group
      - AppWidgetHostView (Search)
        ...
      - Text [ref=4] "Gallery" (Gallery)
  - View (Home)
  - Group
    - Text [ref=5] "Contacts" (Contacts)
    - Text [ref=6] "WebView Browser Tester" (WebView Browser Tester)
    - Text [ref=7] "Camera" (Camera)

3. Toca algo. tap(device="vanilla", ref="5"), tap(device="vanilla", text="Contacts") and tap(device="vanilla", x=102, y=1116) todos abren Contactos y devuelven {"ok": true}. Después de cualquier acción, toma una nueva snapshot, porque las referencias solo son válidas hasta la siguiente.

4. Verifica el resultado. foreground(device="vanilla") ahora informa la aplicación Contactos, y screenshot(device="vanilla") devuelve la pantalla como una imagen que tu agente ve directamente.

Instalar un APK para control de calidad funciona de la misma manera:

install_apk(device="vanilla", apk_path="/path/to/app.apk")
→ {"ok": true, "package": "com.erius.dashtest", "versionName": "1.0", "label": "ERIUS Dash Test",
   "adbOutput": "Performing Streamed Install\nSuccess", "ms": 94, ...}

Consejos y límites

• Los errores se transmiten. Si la API rechaza una acción, la llamada a la herramienta falla con el código de error y el mensaje de la API, p. ej. HTTP 404: SelectorNotFound ... nothing on screen matches {"text": "..."} or HTTP 422: no_launcher_activity. El agente puede leer el mensaje y ajustarse.
• Escribir requiere un campo listo. Las pulsaciones de teclas enviadas mientras un campo aún se está abriendo se pierden. Si tocar un campo abre una nueva pantalla (como hace la búsqueda de Configuración de Android), tócalo, espera con snapshot/wait_for_text, luego llama a type_text sin un objetivo. Verifica el resultado con snapshot.
• Escritura solo ASCII. type_text admite solo ASCII imprimible (una limitación de adb): sin emojis, caracteres acentuados ni escrituras no latinas.
• Desplazamiento por contenedor. scroll necesita la referencia del contenedor desplazable (una línea ScrollView/List en la instantánea). Si el contenedor no tiene referencia, usa swipe.
• Las capturas de pantalla cuestan contexto. La captura de pantalla predeterminada es un JPEG con su lado más largo a 1024 px (decenas de KB). Un PNG de tamaño completo de un teléfono (1440×3120) es de aproximadamente 3 MB, más de lo que muchos clientes MCP aceptan en un solo resultado de herramienta. Prefiere snapshot (texto, mucho más pequeño) y toma capturas de pantalla solo cuando necesites píxeles.
• Coordenadas de una captura de pantalla escalada. x,y son píxeles del dispositivo a menos que pases image_width y image_height (el tamaño de la captura de pantalla de la que los leíste) a tap, long_press o swipe.
• install_apk lee un archivo local. La ruta está en la máquina que ejecuta erius-phone-mcp, no en el teléfono. El APK se transmite desde el disco y se sube completo en cada llamada.
• Un proceso de servidor = una clave API. Para usar varias cuentas, añade varias entradas de servidor con diferentes nombres y claves.
• Límites de velocidad. La API permite aproximadamente 30 solicitudes por segundo por IP y pone en cola como máximo 8 solicitudes por dispositivo; más allá de eso obtienes HTTP 429.

Solución de problemas

• ERIUS_PHONE_API_KEY is not set: la variable no llegó al proceso del servidor. Colócala en el bloque env del cliente, no solo en tu shell. El servidor también imprime una advertencia sobre esto en stderr al inicio, que aparece en los registros MCP de tu cliente.
• no device id given and ERIUS_PHONE_DEFAULT_DEVICE is not set: pasa device= en la llamada a la herramienta o configura ERIUS_PHONE_DEFAULT_DEVICE. list_devices muestra tus ids.
• HTTP 401: la clave es incorrecta o fue revocada. HTTP 403: el id del dispositivo no existe o no está en tu cuenta. Ejecuta whoami para ver qué dispositivos puede usar tu clave.
• HTTP 503 device_offline: el dispositivo se está reiniciando. Reintenta en breve.
• could not reach the ERIUS PHONE API at ...: la URL es incorrecta, o la API no es accesible desde tu máquina. Verifica ERIUS_PHONE_API_URL y aumenta ERIUS_PHONE_TIMEOUT si estás en un enlace lento.

Licencia

MIT. El texto completo de la licencia está en el archivo LICENSE incluido con el paquete.