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.
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.shUna vez que este script se complete, iniciará sesión automáticamente en Ubuntu, dejándote en el prompt:
root@localhost:~#
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#.)
Mientras estés dentro del entorno virtual activo, ejecuta el servidor directamente:
python termux_mcp.py --transport sseUna 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.
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.shRelated MCP server: android-shizuku-mcp
Ejecutar una distribución de Linux como Ubuntu dentro de Termux usando proot-distro ofrece varios beneficios clave:
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.
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.
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.
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).
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.
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).
Ve a Configuración de Android -> Aplicaciones -> Termux:API -> Permisos:
Otorga permisos de Cámara, Ubicación, SMS, Contactos y Almacenamiento.
Desactiva la optimización de batería tanto para Termux como para Termux:API para evitar que Android cierre los servicios en segundo plano.
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.shUna 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/activateEn el entorno activado ((venv)root@localhost:~/Termux-MCP#):
python termux_mcp.py --transport sseLa 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/
==================================================================Puedes conectar cualquier cliente que admita MCP sobre Server-Sent Events (SSE).
Abre Configuración de Cursor -> Features -> MCP.
Haz clic en + Add New MCP Server.
Ingresa:
Name: termux-mcp
Type: SSE
URL: http://YOUR_PHONE_IP:8000/sse (Copia y pega la 'SSE Connect URL' impresa por el servidor)
Haz clic en Save.
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.
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.
This server cannot be deployed
Turns a phone into a camera+Bluetooth remote so AI assistants can see and control any PC.
Cloud Android phones for AI agents: create a phone, read the screen, tap, type, install APKs, park.
Melaya is a remote MCP server. It gives an assistant hands on your own Android phone and browser: it reads the screen through the accessibility tree, then taps, types and navigates inside the apps and sites you allow-list, with no per-app API. It also builds, schedules and runs agent pipelines across 6k+ connected tools. OAuth 2.1, nothing to install.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
