idb-mcp

Um servidor MCP que utiliza o Facebook IDB para automatizar simuladores iOS, fornecendo controle de dispositivos, ações de entrada e capturas de tela via HTTP, SSE ou stdio.

GitHub
11
Experimente este MCPPatrocinado

Documentação

IDB-MCP

PyPI Python Versions License

Um servidor MCP de código aberto e biblioteca Python que encapsula o Facebook IDB para controlar simuladores iOS para automação. Criado pela AskUI.

Este projeto é baseado no CLI do Facebook IDB (fb-idb). Veja o repositório GitHub (facebook/idb) e o pacote Python (fb-idb no PyPI).

O que é

  • Servidor MCP: Expõe um conjunto de ferramentas de automação iOS (listar/selecionar dispositivo, captura de tela, toque, deslizar, digitar, etc.) por meio de transportes MCP (HTTP, SSE ou stdio) usando fastmcp.
  • Módulo Python: Importe para gerenciar e controlar simuladores iOS programaticamente.

Sumário

Principais recursos

  • Gerenciamento de dispositivos 🔧: listar dispositivos, selecionar por UDID ou nome, iniciar/desligar, encerrar IDB.
  • Controle de entrada 👆: toque, deslizar, digitar texto, tocar teclas, tocar botões.
  • Utilitários de tela 🖼️: capturar capturas de tela, consultar tamanho da tela, obter descrição da visualização.
  • Escalonamento de imagem/coordenadas 📐: escalonamento opcional para um viewport alvo para coordenadas consistentes.

Limitações

⚠️ Apenas simuladores iOS são suportados para controle de UI. Devido às restrições de segurança do iOS, idb não pode interagir ou automatizar a UI em dispositivos físicos reais. A AskUI oferece uma solução para automação de UI em dispositivos reais—entre em contato com support@askui.com para mais informações.

Requisitos

  • Funciona apenas em macOS.

  • Python >= 3.10

  • Xcode com Simuladores iOS instalados e configurados.

    • Verifique se os simuladores estão visíveis:

      xcrun xctrace list devices

  • Companheiro Facebook IDB (usando brew):

    brew tap facebook/fb
brew install idb-companion

Instalação

pip install idb-mcp

Início rápido (CLI)

Por que MCP?

Usar MCP permite que suas ferramentas de IA favoritas se conectem ao idb-mcp perfeitamente. O cliente cuida do lançamento e da comunicação com o servidor, então você pode solicitar capturas de tela, toques, deslizes e muito mais—sem sair do seu fluxo de trabalho. ✨

Iniciar servidor MCP

O pacote instala um 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()

Adicionar às suas ferramentas favoritas

Você pode usar idb-mcp em qualquer cliente compatível com MCP (por exemplo, Cursor, Claude Desktop) adicionando uma entrada de servidor ao arquivo de configuração MCP do seu cliente. O cliente iniciará o servidor sob demanda.

Passos:

  • Abra o arquivo de configuração MCP do seu cliente (a localização varia conforme o cliente).
  • Adicione uma entrada chamada askui-idb-mcp que inicia o servidor via STDIO e define um tamanho de tela alvo recomendado.

Exemplo de configuração:

usando uv (certifique-se de ter o uv instalado):

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

Alternativa (se idb-mcp estiver diretamente no seu PATH sem uv):

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

Observações:

  • A configuração --target-screen-size 1280 800 melhora a confiabilidade das coordenadas, especialmente para modelos como Claude.

Configuração

  • Tamanho da tela alvo 📐: Você pode escalar capturas de tela e entradas de coordenadas para um viewport alvo ao iniciar o servidor MCP via CLI (--target-screen-size W H) ou programaticamente (target_screen_size=(W, H)).
  • Modo 📐: Você pode iniciar o servidor MCP no modo stdio, http ou sse.
  • Porta 📐: Você pode iniciar o servidor MCP em uma porta específica via CLI (--port PORT) ou programaticamente (port=PORT).

Solução de problemas

  • Não consigo ver dispositivos 🔍: Certifique-se de ter um simulador iOS ou dispositivo conectado e em execução. Verifique com:

    xcrun xctrace list devices

    Exemplo de saída:

    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 tela de alta resolução com alguns LLMs 🧠: Alguns backends de LLM têm dificuldade em processar imagens de resolução muito alta, resultando em detecção de coordenadas ruim ou erros de toque. Use o redimensionamento via --target-screen-size (ou target_screen_size em Python) para reduzir capturas de tela e coordenadas. Para modelos Claude, recomendamos 1280 800.

Desenvolvimento

Este repositório usa PDM e Ruff para ferramentas de desenvolvimento.

# 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

Contribuindo

Contribuições são bem-vindas! 🙌 Por favor, abra uma issue ou pull request no GitHub. Perguntas? Envie um e-mail para support@askui.com.

Licença

Licença MIT

Links