Termux API & PRoot-Distro Ubuntu con servidor MCP

Este proyecto proporciona un script de arranque para instalar Ubuntu bajo proot-distro en Android a través de Termux, vincular las API del sistema Android en él y lanzar un servidor Model Context Protocol (MCP) basado en Python.

Con este servidor MCP ejecutándose en tu teléfono, puedes otorgar a cualquier cliente de IA externo (como Cursor, Claude Desktop, Windsurf o agentes HTTP personalizados) la capacidad completa para controlar el hardware de tu dispositivo Android, leer sensores, obtener comunicaciones y ejecutar comandos de shell.

Inicio rápido (configuración en tres pasos)

Paso 1: Instalar y configurar Ubuntu en Termux

Ejecuta este comando dentro de tu terminal nativa de Termux para instalar, configurar e iniciar sesión en Ubuntu. (Esto descarga el script primero para que stdin permanezca conectado a tu teclado, permitiendo que inicie sesión correctamente).

curl -sLO https://raw.githubusercontent.com/AbuZar-Ansarii/Termux-MCP/main/install_ubuntu.sh && chmod +x install_ubuntu.sh && ./install_ubuntu.sh

Una vez que este script se complete, iniciará sesión automáticamente en Ubuntu, dejándote en el prompt: root@localhost:~#

Paso 2: Clonar y configurar MCP (dentro de Ubuntu)

Una vez dentro del contenedor de Ubuntu (root@localhost:~#), copia y pega este comando para clonar el repositorio, ejecutar el script de configuración y activar el entorno virtual:

git clone https://github.com/AbuZar-Ansarii/Termux-MCP.git && cd Termux-MCP && chmod +x setup_mcp.sh && ./setup_mcp.sh && source venv/bin/activate

(Agregar la declaración source venv/bin/activate asegura que se ejecute en el contexto de tu shell padre. Una vez completado, te encontrarás dentro del entorno virtual activado en el prompt: (venv)root@localhost:~/Termux-MCP#.)

Paso 3: Ejecutar el servidor MCP

Mientras estés dentro del entorno virtual activo, ejecuta el servidor directamente:

python termux_mcp.py --transport sse

Una vez en ejecución, el servidor detectará la dirección IP de tu teléfono y mostrará una URL de conexión copiable (por ejemplo, http://192.168.1.15:8000/sse) para conectar directamente a tu cliente de IA.

Comando de acceso rápido para futuras ejecuciones

Para futuras ejecuciones (desde Termux nativo, sin iniciar sesión manualmente ni activar el entorno), puedes iniciar el servidor con un solo comando:

proot-distro login ubuntu -- bash /root/run_mcp.sh

Related MCP server: android-shizuku-mcp

¿Por qué PRoot-Distro Ubuntu?

Ejecutar una distribución de Linux como Ubuntu dentro de Termux usando proot-distro ofrece varios beneficios clave:

1. Compatibilidad con Glibc (GNU C Library): Android y Termux nativo usan Bionic libc, que difiere en rutas y estándares. Muchos paquetes compilados, binarios de bases de datos, módulos de Node y bibliotecas de Python requieren glibc estándar para ejecutarse sin fallos de compilación. PRoot-Distro Ubuntu proporciona un entorno glibc estándar.

2. Abundancia de paquetes y ecosistema: Ubuntu te da acceso a los enormes archivos de paquetes apt. Si tu flujo de trabajo requiere herramientas de servidor Linux estándar, paquetes de escritorio o servicios compilados, ejecutarlos en el rootfs de Ubuntu es mucho más robusto que parchearlos para Android/Bionic nativo.

3. Aislamiento y sandbox: Desarrollar dentro de PRoot Ubuntu mantiene tu sistema de archivos de Termux anfitrión limpio y modular. Si algo se rompe o quieres empezar de nuevo, simplemente puedes restablecer el contenedor de la distribución sin perder tus configuraciones de Termux.

4. Puente de API de hardware: Nuestro script de arranque vincula la carpeta nativa $PREFIX de Termux dentro de Ubuntu. Esto significa que obtienes lo mejor de ambos mundos: un entorno Linux Ubuntu completo que aún tiene acceso directo por línea de comandos a las API de Android (como cámara, toast, ubicación y sensores).

Características (herramientas MCP)

El servidor MCP expone un conjunto completo de herramientas para controlar tu teléfono:

• Sistema y hardware:

  • get_battery_status: Lee el nivel de batería del dispositivo, salud, temperatura y estado de carga.

  • toggle_torch: Enciende o apaga la linterna.

  • set_screen_brightness: Cambia el brillo de la pantalla (0-255).

  • get_volume_info y set_volume: Lee o establece niveles para los flujos de volumen de alarma, música, timbre, llamada, sistema y notificaciones.

• Comunicación:

  • list_contacts: Lista todos los nombres de contactos y números de teléfono almacenados en el teléfono.

  • get_call_log: Recupera el historial de llamadas recientes.

  • list_sms y send_sms: Lista mensajes de entrada/enviados y envía nuevos mensajes de texto.

• Sensores y red:

  • get_location: Recupera coordenadas GPS precisas o basadas en red.

  • get_wifi_connection_info: Obtiene metadatos de conexión Wi-Fi (SSID, BSSID, IP, velocidad de enlace).

  • get_telephony_device_info: Consulta el operador de telefonía, la intensidad de la señal y el tipo de red.

• Medios y fotos:

  • take_photo: Toma fotos con la cámara frontal o trasera y las guarda en una ruta de archivo en el dispositivo.

  • tts_speak: Sintetiza habla usando Google TTS.

• Interacción con el usuario y portapapeles:

  • show_toast: Muestra notificaciones toast temporales en la pantalla del teléfono.

  • vibrate_phone: Vibra el dispositivo durante una duración determinada.

  • clipboard_get y clipboard_set: Lee y escribe el portapapeles de Android.

  • show_notification: Muestra notificaciones estándar de Android.

  • prompt_user_dialog: Muestra un diálogo interactivo de entrada de texto en el teléfono, permitiéndote escribir una respuesta de vuelta al cliente de IA.

  • share_text: Comparte texto directamente en la hoja de compartir nativa de Android.

• Ejecución arbitraria:

  • execute_command: Ejecuta cualquier comando de shell arbitrario directamente en el host nativo de Termux.

Instalación detallada paso a paso

Paso 1: Instalar Termux y Termux:API en Android

1. Instala la aplicación Termux y la aplicación Termux:API.

   • Requisito: Instala ambas aplicaciones desde F-Droid (no mezcles versiones de F-Droid y Play Store, ya que no se firmarán/vincularán juntas).

2. Ve a Configuración de Android -> Aplicaciones -> Termux:API -> Permisos:

   • Otorga permisos de Cámara, Ubicación, SMS, Contactos y Almacenamiento.

3. Desactiva la optimización de batería tanto para Termux como para Termux:API para evitar que Android cierre los servicios en segundo plano.

Paso 2: Ejecutar el script de configuración

Abre Termux y pega el siguiente comando:

curl -sLO https://raw.githubusercontent.com/AbuZar-Ansarii/Termux-MCP/main/install_ubuntu.sh && chmod +x install_ubuntu.sh && ./install_ubuntu.sh

Paso 3: Ejecutar la configuración del servidor MCP

Una vez dentro del contenedor de Ubuntu:

git clone https://github.com/AbuZar-Ansarii/Termux-MCP.git && cd Termux-MCP && chmod +x setup_mcp.sh && ./setup_mcp.sh && source venv/bin/activate

Paso 4: Lanzar el servidor

En el entorno activado ((venv)root@localhost:~/Termux-MCP#):

python termux_mcp.py --transport sse

La terminal imprimirá la URL de conexión:

==================================================================
   🤖 Termux MCP Server Running in SSE Mode
==================================================================
   👉 SSE Connect URL: http://192.168.1.15:8000/sse
   👉 Messages URL:    http://192.168.1.15:8000/messages/
==================================================================

Paso 5: Conectar a tu cliente de IA

Puedes conectar cualquier cliente que admita MCP sobre Server-Sent Events (SSE).

Conectar Cursor:

1. Abre Configuración de Cursor -> Features -> MCP.

2. Haz clic en + Add New MCP Server.

3. Ingresa:

   • Name: termux-mcp

   • Type: SSE

   • URL: http://YOUR_PHONE_IP:8000/sse (Copia y pega la 'SSE Connect URL' impresa por el servidor)

4. Haz clic en Save.

Conectar Claude Desktop (alternativa Stdio sobre SSH)

Si prefieres ejecutar comandos stdio locales a través de SSH, consulta Opción B en la documentación del repositorio para configurar claves OpenSSH y configurar tu %APPDATA%\Claude\claude_desktop_config.json local.

Solución de problemas

• La llamada a la herramienta se cuelga: Si una llamada a una herramienta (como get_location o take_photo) se cuelga, verifica que la aplicación Termux:API tenga permisos otorgados en la configuración de Android y que el ahorro de batería esté desactivado.

• Conexión rechazada: Asegúrate de que tu PC y tu teléfono estén conectados a la misma red Wi-Fi y que el servidor esté en ejecución.

• Ejecución en segundo plano de Termux: Android puede suspender los procesos de Termux cuando la pantalla está bloqueada. Desliza hacia abajo el cajón de notificaciones de Android y asegúrate de que Termux muestre "1 sesión" con "Acquire wake lock" habilitado, manteniéndolo en ejecución en segundo plano.