PocketMCP

Convierte tu teléfono Android en un servidor MCP (Model Context Protocol). Los agentes de IA y scripts de escritorio pueden llamar a tu teléfono para obtener datos en vivo y realizar acciones a través de la LAN.

GitHub
14
Prueba este MCPPatrocinado

Documentación

PocketMCP

Convierte tu teléfono Android en un servidor MCP (Model Context Protocol). Los agentes de IA y los scripts de escritorio pueden llamar a tu teléfono para obtener datos en vivo y realizar acciones a través de LAN o Tailscale.

Descarga (Pre-lanzamiento de prueba)

  • Última versión de prueba: v1.0.0-beta.1
  • Esta compilación está marcada como pre-lanzamiento y puede contener errores mientras continúa el desarrollo activo.

Compromiso de Código Abierto

PocketMCP es completamente de código abierto y la funcionalidad principal es gratuita. El proyecto tiene licencia MIT y las contribuciones de la comunidad son bienvenidas.

Por qué es útil

Casos de uso de alto valor para todos los usuarios:

  1. Centro de Comunicación: Envía mensajes de WhatsApp, Instagram, Messenger y haz llamadas desde el escritorio
  2. Automatización de Redes Sociales: Interactúa con Instagram, YouTube, X/Twitter automáticamente
  3. Gestión de Notificaciones: Monitorea y responde a todas las notificaciones del teléfono en tiempo real
  4. Verificación diaria de estado: "¿Cuál es mi batería y dónde está mi teléfono ahora mismo?"
  5. Búsqueda de contactos: "Encuentra el número de Alice en mis contactos."
  6. Control del ecosistema de aplicaciones: Inicia y gestiona más de 309 aplicaciones instaladas
  7. Diagnóstico del teléfono: Ejecuta verificaciones seguras de shell sin desbloquear el teléfono.

Herramientas integradas

HerramientaDescripción
device_infoBatería, modelo, sistema operativo, red, memoria
get_locationMejor ubicación reciente de los proveedores del dispositivo
search_contactsBusca contactos por nombre
make_callRealiza llamadas telefónicas a cualquier número
send_messageEnvía mensajes a través de WhatsApp, Instagram, Messenger, Google Messages
send_whatsapp_business_messageEnviador dedicado de WhatsApp Business seguro para contactos
whatsapp_automationAutomatización avanzada de WhatsApp con control de accesibilidad
social_mediaInteracciones con Instagram, YouTube, X/Twitter
app_actionsAcciones predefinidas en JSON para simplificar la automatización de aplicaciones
notificationsMonitoreo y gestión de notificaciones en tiempo real
shellEjecuta comandos de shell con filtros de seguridad y tiempo límite
flashlightEnciende/apaga/alterna la linterna y lee su estado
launch_appAbre una aplicación instalada por paquete o nombre
list_appsLista aplicaciones instaladas ejecutables (se detectan más de 309)
global_actionInicio/atrás/recientes/notificaciones/ajustes rápidos/pantalla de bloqueo
scroll_screenDesplaza la aplicación actual mediante gesto de accesibilidad
search_screenEncuentra el campo de búsqueda en la pantalla actual y escribe la consulta de forma segura
tapToca por texto visible/descripción de contenido o coordenadas de pantalla
volume_controlLee y cambia los niveles de volumen de transmisión
phone_alertHace sonar y/o vibrar el teléfono para localizarlo rápidamente
voice_recordGraba notas de voz desde el micrófono
transcribe_audioConversión de voz a texto desde el micrófono o ruta de archivo de audio local
transcribe_fileTranscripción directa de archivos de audio por ruta
transcribe_whatsapp_audioTranscribe la última nota de voz de WhatsApp/WhatsApp Business
human_commandEnrutador de comandos en lenguaje natural entre las principales herramientas
http_requestRealiza solicitudes HTTP salientes desde el teléfono
read_fileLee archivos desde rutas de almacenamiento permitidas

🆕 Nuevas Funciones (v.0+)

📞 Llamadas Telefónicas y Mensajería

  • Llamadas Directas: Realiza llamadas a cualquier número con soporte de nombre de contacto
  • Mensajería Multiplataforma: WhatsApp, Instagram, Messenger, Google Messages
  • Soporte de WhatsApp Business: Prioriza WhatsApp Business cuando está instalado
  • Integración de Enlaces Profundos: Abre aplicaciones con contenido prellenado

🤖 Automatización Avanzada de WhatsApp

  • Automatización Completa: Envía mensajes con selección de contacto y escritura
  • Control Paso a Paso: Selecciona contactos, escribe mensajes, presiona enviar/cancelar
  • Integración de Accesibilidad: Automatización completa de la interfaz de usuario mediante el servicio de accesibilidad
  • Business y Personal: Soporta ambas variantes de WhatsApp

🌐 Interacciones en Redes Sociales

  • Instagram: Búsqueda de perfiles, interacciones con publicaciones (me gusta, comentar, compartir)
  • YouTube: Búsqueda de videos, me gusta/no me gusta/comentar en videos
  • X/Twitter: Búsqueda de perfiles, interacciones con publicaciones
  • Enlaces Profundos: Navegación directa a contenido específico

🔔 Notificaciones en Tiempo Real

  • Monitoreo en Vivo: Captura todas las notificaciones del dispositivo en tiempo real
  • Datos Completos: Título, texto, aplicación, hora, prioridad, visibilidad
  • Acceso Histórico: Notificaciones recientes con búsqueda y filtrado
  • Gestión: Borrar historial, verificar estado, obtener recuentos

Modelo de seguridad

  • Autenticación con clave API soportada mediante X-API-Key (recomendado).
  • Uso de red local por defecto; usa Tailscale para acceso remoto.
  • La herramienta de shell bloquea comandos de alto riesgo y aplica límites de tiempo y salida.
  • Las lecturas de archivos están restringidas al almacenamiento de la aplicación y a las raíces de almacenamiento externo.
  • Las URLs de bucle local están bloqueadas en http_request.
  • Servicio de Accesibilidad: Requerido para funciones de automatización avanzada.
  • Acceso a Notificaciones: Requerido para el monitoreo de notificaciones en tiempo real.

Modelo de confiabilidad

  • El servicio en primer plano de Android mantiene vivo el servidor MCP.
  • El ciclo de vida de inicio/detención/estado es explícito (START, STOP, QUERY_STATUS).
  • La interfaz de usuario refleja el estado real del servicio mediante transmisiones de estado.
  • Detección Mejorada de Aplicaciones: Detecta más de 309 aplicaciones ejecutables (antes 25).
  • Alternativas Elegantes: Instrucciones de interacción manual cuando la automatización no es posible.

Inicio rápido

1) Instalar la aplicación

Opción A: instalar desde el APK de pre-lanzamiento

  • Descarga PocketMCP-debug.apk desde v1.0.0-beta.1
  • Instala con ADB:
adb install -r PocketMCP-debug.apk

Opción B: compilar desde el código fuente e instalar

./gradlew assembleDebug
adb install app/build/outputs/apk/debug/app-debug.apk

2) Iniciar el servidor en la aplicación

  1. Abre PocketMCP.
  2. Configura el puerto (por defecto 8080).
  3. Genera o pega la clave API.
  4. Inicia el servidor desde el interruptor o botón.
  5. Copia el endpoint/configuración desde la sección de Conexión Rápida.

3) Habilitar Permisos

Requerido para funcionalidad completa:

  • Ubicación: ACCESS_FINE_LOCATION (solicitado automáticamente al iniciar)
  • Contactos: READ_CONTACTS (solicitado automáticamente al iniciar)
  • Cámara: CAMERA (solicitado automáticamente al iniciar)
  • Teléfono: permiso CALL_PHONE en la configuración de la aplicación
  • Micrófono: permiso RECORD_AUDIO en la configuración de la aplicación
  • SMS: permisos SEND_SMS, READ_SMS
  • Audio/Almacenamiento: READ_MEDIA_AUDIO o READ_EXTERNAL_STORAGE (solicitado automáticamente)
  • Notificaciones: Configuración > Aplicaciones > Acceso Especial > Acceso a Notificaciones
  • Accesibilidad: Configuración > Aplicaciones > Acceso Especial > Servicios de Accesibilidad

4) Verificar el servidor

# health
curl http://192.168.1.100:8080/health

# list tools
curl -X POST http://192.168.1.100:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Conexión con emulador (AVD de Android Studio)

Si PocketMCP se ejecuta dentro de un emulador de Android, no uses 10.0.2.15 desde la configuración de tu cliente MCP en el host.

Usa el reenvío de puertos de ADB y localhost:

powershell -ExecutionPolicy Bypass -File .\scripts\setup-emulator-mcp.ps1

Luego configura la URL de MCP como:

http://127.0.0.1:8080/mcp

Notas:

  • 10.0.2.15 es interno del emulador (no accesible desde el host).
  • 10.0.2.2 es para emulador -> host, no host -> emulador.

Ejemplo de Configuración de Cliente MCP

Usa mcp-config.example.json como plantilla.

{
  "mcpServers": {
    "phone": {
      "type": "streamableHttp",
      "url": "http://192.168.1.100:8080/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Puente Stdio (para clientes MCP solo-stdio)

PocketMCP incluye un puente stdio reforzado en mcp-bridge/bridge.mjs que actúa como proxy de llamadas MCP stdio hacia el endpoint HTTP MCP de tu teléfono.

cd mcp-bridge
npm install
node bridge.mjs --url http://192.168.1.100:8080/mcp --api-key your-api-key --verbose

Opciones de configuración del puente:

  • --url: URL MCP del teléfono de destino (agrega automáticamente http:// si falta)
  • --api-key: clave API enviada como X-API-Key
  • --timeout-ms: tiempo límite por solicitud (por defecto 20000)
  • --tools-ttl-ms: TTL de caché de herramientas (por defecto 30000)
  • --no-tool-cache: deshabilitar caché de herramientas
  • --verbose: emitir registros detallados del puente a stderr

Variables de entorno equivalentes:

  • POCKET_MCP_URL
  • POCKET_MCP_API_KEY
  • POCKET_MCP_TIMEOUT_MS
  • POCKET_MCP_TOOLS_TTL_MS
  • POCKET_MCP_DISABLE_TOOL_CACHE=1
  • POCKET_MCP_VERBOSE=1

Ejemplo de Cliente Python

from pocket_mcp_client import PocketMCPClient

phone = PocketMCPClient("http://192.168.1.100:8080", api_key="your-api-key")

print(phone.device_info())
print(phone.list_apps(limit=25))
print(phone.notifications("list", 10))
print(phone.human_command("vibrate my phone for 5 seconds"))

El cliente Python ahora incluye reintentos, excepciones tipadas, validación de argumentos más estricta y una CLI:

# health check (default action)
python3 pocket_mcp_client.py 192.168.1.100:8080 your-api-key

# list tools
python3 pocket_mcp_client.py 192.168.1.100:8080 your-api-key --list-tools

# call one tool with JSON args
python3 pocket_mcp_client.py 192.168.1.100:8080 your-api-key \
  --call send_message \
  --args '{"app":"whatsapp","phone_number":"+15551234567","message":"hello from desktop"}'

Permisos

Algunas herramientas requieren permisos especiales o servicios de Android:

  • Teléfono (CALL_PHONE)
  • Micrófono (RECORD_AUDIO)
  • SMS (SEND_SMS, READ_SMS, RECEIVE_SMS)
  • Acceso a notificaciones (Notification Listener)
  • Servicio de accesibilidad (para automatización de interfaz de usuario)

Modelo de Seguridad

  • Autenticación con clave API mediante X-API-Key (recomendado)
  • Red local primero; acceso remoto a través de redes privadas como Tailscale
  • Restricciones de comandos de shell con límites de tiempo y salida
  • Restricciones de rutas de lectura de archivos
  • Bloqueo de URLs de bucle local para http_request

Notas de Confiabilidad

  • Se ejecuta como un servicio en primer plano de Android
  • Ciclo de vida del servicio explícito (START, STOP, QUERY_STATUS)
  • Las actualizaciones de transmisión de estado se reflejan en la interfaz de usuario

Hoja de ruta

  • Herramientas de captura de cámara
  • Más automatizaciones basadas en accesibilidad
  • Soporte de WebSocket
  • Flujo de trabajo de emparejamiento con un toque
  • Flujos de comandos por voz

Licencia

MIT