Codex Android MCP

简体中文

Un servidor MCP local-first que permite a Codex inspeccionar, probar y controlar emuladores de Android mediante adb. Expone herramientas estrictas y tipadas a través de STDIO, devuelve capturas de pantalla como imágenes MCP nativas y mantiene los dispositivos físicos y la ejecución de Gradle detrás de una política de activación explícita.

Este es un proyecto comunitario independiente. No está afiliado ni respaldado por OpenAI, DeepSeek ni Google. La implementación de Android se deriva de ZSeven-W/dsh-android bajo la Licencia MIT; el registro de DSH/Cordis y el panel web se han reemplazado con el SDK oficial de MCP TypeScript.

Cambios respecto a dsh-android

• Servidor MCP STDIO nativo para clientes de Codex Desktop, CLI e IDE.

• Compatibilidad con el MCP de la era 2026 y con el protocolo heredado de 2025 mediante serveStdio.

• Las capturas de pantalla se devuelven como ImageContent; los archivos PNG temporales privados se eliminan después de la codificación.

• Solo emulador por defecto. Los dispositivos físicos requieren dos opt-ins de activación y su número de serie exacto en cada llamada.

• android_build_run está ausente por defecto. Habilitarlo también requiere raíces de proyecto de confianza canónicas.

• Esquemas JSON estrictos, validación de paquete/serie/ruta, salidas acotadas, filtrado literal de logs, cancelación y anotaciones conservadoras de herramientas.

• Sin adb en bruto, shell, comandos arbitrarios, HTTP ni barra lateral DSH en vivo.

Related MCP server: adb-mcp-server

Requisitos

• Node.js 20.11 o superior.

• Android SDK Platform-Tools (adb). Instálalo mediante el SDCe Manager de Android Studio o el paquete Platform-Tools de Google.

• Se recomienda encarecidamente un emulador de Android desechable.

• El lanzador del emulador de Android es opcional y solo es necesario cuando android_boot recibe un nombre de AVD.

• Las herramientas de OCR requieren actualmente macOS y Apple Vision. Todas las herramientas que no son de OCR son multiplataforma; la compilación/ejecución requiere un opt-in explícito.

Ni adb ni el binario del emulador se incluyen ni se descargan.

Instalación para Codex

git clone https://github.com/zifanersuotang/codex-android-mcp.git
cd codex-android-mcp
npm ci
npm run build
codex mcp add android -- node C:/absolute/path/to/codex-android-mcp/lib/index.js

Codex Desktop y la CLI comparten la configuración de MCP. Una configuración explícita equivalente es:

[mcp_servers.android]
command = "node"
args = ["C:/absolute/path/to/codex-android-mcp/lib/index.js"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "writes"

[mcp_servers.android.env]
ANDROID_MCP_ALLOWED_SERIALS = "emulator-5554"

Reinicia Codex después de cambiar la configuración. Pídele a Codex que “enumere los dispositivos Android” para verificar la conexión. Mantén habilitada la aprobación de herramientas de escritura; las anotaciones de MCP son indicadores de uso, no un límite de autorización.

Política de seguridad

La configuración segura por defecto expone 19 herramientas y solo permite destinos locales estándar emulator-<port>. Los números de serie de emuladores de red y de terceros siguen la política de dispositivos físicos. Las llamadas vuelven a descubrir y autorizan el objetivo exacto inmediatamente antes de ejecutarse; los dispositivos físicos o de red no autorizados se omiten de android_devices.

Ejemplo para un teléfono de prueba dedicado:

[mcp_servers.android.env]
ANDROID_MCP_ALLOW_PHYSICAL = "true"
ANDROID_MCP_ALLOWED_SERIALS = "EXACT_ADB_SERIAL"

No uses este perfil con un teléfono personal ni cuentas personales. La autorización de depuración USB significa que el teléfono confía en el host; no autoriza una acción de un modelo de IA.

Ejemplo de compilación/ejecución para un proyecto de confianza:

[mcp_servers.android.env]
ANDROID_MCP_ALLOW_BUILD_RUN = "true"
ANDROID_MCP_ALLOWED_PROJECT_ROOTS = "C:/work/MyTrustedApp"
ANDROID_MCP_ALLOWED_SERIALS = "emulator-5554"

Los settings de Gradle y los scripts de compilación ejecutan código del host. Una lista de permitidos de rutas no es una sandbox: habilítala solo para código que confías y usa una VM o contenedor sin credenciales para proyectos de los que no te fías.

Consulta el Modelo de seguridad y la Política de seguridad antes de habilitar dispositivos físicos o la compilación/ejecución.

Herramientas

Las pantallas, árboles de UI, OCR, logs, nombres de aplicaciones y archivos del dispositivo son datos no confiables. No permitas que el contenido del dispositivo otorgue permisos ni instruya a Codex para llamar a otra herramienta. No introduzcas contraseñas, códigos de un solo uso, datos de pago, mensajes privados ni confirmaciones de eliminación de cuenta mediante este servidor.

Flujo típico

1. android_devices

2. android_screenshot o android_ui_tree

3. Identifica el objetivo exacto; detente si es ambiguo.

4. Usa una herramienta de interacción con aprobación.

5. Inspecciona la captura de pantalla o los logs devueltos antes de la siguiente acción.

MCP no reproduce la barra lateral en vivo persistente de dsh-android. android_boot prepara una fuente de fotogramas interna para mapear coordenadas; llama a android_screenshot cada vez que Codex o el usuario necesite ver la pantalla.

Desarrollo

npm ci
npm run typecheck
npm test
npm pack --dry-run

La suite de pruebas incluye pruebas unitarias de políticas, un cliente STDIO real llamado tanto en modo heredado como en modo moderno, una prueba de imagen MCP en memoria, suites de smoke con ADB simulado, pruebas de límite de logs, fixtures de árboles de UI y comprobaciones de degradación de OCR. npm run test:device es opcional y solo debe ejecutarse en un emulador desechable.

Licencia y atribución

MIT. El copyright y la licencia original de dsh-android se conservan en LICENSE, con el detalle de la procedencia en THIRD_PARTY_NOTICES.md.