idb-mcp

Un servidor MCP que utiliza Facebook IDB para automatizar simuladores de iOS, proporcionando control de dispositivos, acciones de entrada y capturas de pantalla a través de HTTP, SSE o stdio.

GitHub
11
Prueba este MCPPatrocinado

Documentación

IDB-MCP

PyPI Python Versions License

Un servidor MCP de código abierto y una biblioteca de Python que envuelve Facebook IDB para controlar simuladores de iOS para automatización. Creado por AskUI.

Este proyecto se basa en la CLI de Facebook IDB (fb-idb). Consulte el repositorio de GitHub (facebook/idb) y el paquete de Python (fb-idb en PyPI).

Qué es

  • Servidor MCP: Expone un conjunto de herramientas de automatización de iOS (listar/seleccionar dispositivo, captura de pantalla, tocar, deslizar, escribir, etc.) a través de transportes MCP (HTTP, SSE o stdio) usando fastmcp.
  • Módulo de Python: Importar para gestionar y controlar simuladores de iOS programáticamente.

Tabla de contenidos

Características principales

  • Gestión de dispositivos 🔧: listar dispositivos, seleccionar por UDID o nombre, arrancar/apagar, matar IDB.
  • Control de entrada 👆: tocar, deslizar, escribir texto, tocar teclas, tocar botones.
  • Utilidades de pantalla 🖼️: capturar capturas de pantalla, consultar tamaño de pantalla, obtener descripción de vista.
  • Escalado de imagen/coordenadas 📐: escalado opcional a un viewport objetivo para coordenadas consistentes.

Limitaciones

⚠️ Solo se admiten simuladores de iOS para el control de la interfaz de usuario. Debido a las restricciones de seguridad de iOS, idb no puede interactuar ni automatizar la interfaz de usuario en dispositivos físicos reales. AskUI ofrece una solución para la automatización de la interfaz de usuario en dispositivos reales: contacte con support@askui.com para obtener más información.

Requisitos

  • Se ejecuta solo en macOS.

  • Python >= 3.10

  • Xcode con simuladores de iOS instalados y configurados.

    • Verifique que los simuladores sean visibles:

      xcrun xctrace list devices

  • Compañero de Facebook IDB (usando brew):

    brew tap facebook/fb
brew install idb-companion

Instalación

pip install idb-mcp

Inicio rápido (CLI)

¿Por qué MCP?

Usar MCP permite que tus herramientas de IA favoritas se conecten a idb-mcp sin problemas. El cliente se encarga de lanzar y comunicarse con el servidor, por lo que puedes pedir capturas de pantalla, toques, deslizamientos y más, sin salir de tu flujo de trabajo. ✨

Iniciar servidor MCP

El paquete instala un comando idb-mcp.

# Start MCP server over HTTP (default host/port managed by fastmcp)
idb-mcp start http

# Or start over SSE
idb-mcp start sse

# Or start over stdio
idb-mcp start stdio

# Optionally scale images/coordinates to a given target viewport (width height)
idb-mcp start http --target-screen-size 1280 800

# Discover available options
idb-mcp --help
idb-mcp start --help

Uso programático (Python)

from idb_mcp import IDBController, IOSDevice

# Initialize the IDB controller
controller = IDBController()
# Select the device by name
selected_device: IOSDevice = controller.select_device_by_name("iPhone 17 Pro Max")
# Boot the selected device
selected_device.boot()
# Get the current view description of the selected device
current_view_description: str = selected_device.get_current_view_description()
print(current_view_description)
# Shutdown the selected device
selected_device.shutdown()

Añadir a tus herramientas favoritas

Puedes usar idb-mcp en cualquier cliente compatible con MCP (por ejemplo, Cursor, Claude Desktop) añadiendo una entrada de servidor a la configuración MCP de tu cliente. El cliente lanzará el servidor bajo demanda.

Pasos:

  • Abre el archivo de configuración MCP de tu cliente (la ubicación varía según el cliente).
  • Añade una entrada llamada askui-idb-mcp que inicie el servidor a través de STDIO y establezca un tamaño de pantalla objetivo recomendado.

Ejemplo de configuración:

usando uv (asegúrate de tener uv instalado):

{
  "mcpServers": {
    "askui-idb-mcp": {
      "command": "uvx",
      "args": [
        "idb-mcp@latest",
        "start",
        "stdio",
        "--target-screen-size",
        "1280",
        "800"
      ]
    }
  }
}

Alternativa (si idb-mcp está directamente en tu PATH sin uv):

{
  "mcpServers": {
    "askui-idb-mcp": {
      "command": "idb-mcp",
      "args": [
        "start",
        "stdio",
        "--target-screen-size",
        "1280",
        "800"
      ]
    }
  }
}

Notas:

  • El ajuste --target-screen-size 1280 800 mejora la fiabilidad de las coordenadas, especialmente para modelos como Claude.

Configuración

  • Tamaño de pantalla objetivo 📐: Puedes escalar capturas de pantalla y entradas de coordenadas a un viewport objetivo al iniciar el servidor MCP mediante CLI (--target-screen-size W H) o programáticamente (target_screen_size=(W, H)).
  • Modo 📐: Puedes iniciar el servidor MCP en modo stdio, http o sse.
  • Puerto 📐: Puedes iniciar el servidor MCP en un puerto específico mediante CLI (--port PORT) o programáticamente (port=PORT).

Solución de problemas

  • No se ven dispositivos 🔍: Asegúrate de tener un simulador o dispositivo iOS conectado y en ejecución. Verifica con:

    xcrun xctrace list devices

    Ejemplo de salida:

    iPhone 17 Simulator (26.0) (32E2219C-ED40-452F-9A4D-XXXXXXX)
iPhone 17 Pro Simulator (26.0) (764CCCB7-D84D-46EC-B62D-XXXXXXX)
iPhone 17 Pro Max Simulator (26.0) (065382B5-56B4-4864-8174-XXXXXXX)

  • Capturas de pantalla de alta resolución con algunos LLM 🧠: Algunos backends de LLM tienen dificultades para procesar imágenes de muy alta resolución, lo que resulta en una detección de coordenadas deficiente o errores de toque. Usa el reescalado mediante --target-screen-size (o target_screen_size en Python) para reducir la resolución de capturas y coordenadas. Para modelos Claude, recomendamos 1280 800.

Desarrollo

Este repositorio utiliza PDM y Ruff para las herramientas de desarrollo.

# Install dev deps
pip install pdm
pdm install --with dev

# Lint / Format
pdm run lint-check
pdm run format-check
# Type check
pdm run type-check

Contribuciones

¡Las contribuciones son bienvenidas! 🙌 Por favor, abre un issue o pull request en GitHub. ¿Preguntas? Escríbenos a support@askui.com.

Licencia

Licencia MIT

Enlaces