iphone-mirror-mcp

Opere um iPhone real via macOS iPhone Mirroring, com toques, deslizes, OCR, além de automação de build/teste via Xcode em simuladores e dispositivos. Sem necessidade de jailbreak.

GitHub

Documentação

iphone-mirror-mcp

Deixe qualquer LLM controlar um iPhone real.

Um servidor MCP que controla um iPhone físico através do aplicativo iPhone Mirroring integrado do macOS e automatiza testes de desenvolvimento Xcode — compilar, testar, instalar e iniciar em simuladores e dispositivos, e depois operar o aplicativo na tela espelhada com toques, deslizes, digitação e OCR.

Sem jailbreak. Nada instalado no telefone. Sem alvo XCUITest.

run_on_iphone (build → install → launch on the paired iPhone)
   → screenshot / read_screen / tap / paste_text     drive the app on-device
   → wait_for_text / tap with expect / sim_log       assert what the user sees

63 ferramentas. Funciona com Claude, GPT, Gemini, modelos locais — qualquer coisa que fale MCP via stdio.

Início rápido

git clone https://github.com/nickatnight96/iphone-mirror-mcp.git
cd iphone-mirror-mcp
./install.sh

O instalador verifica sua máquina, compila um binário de lançamento, verifica permissões de ponta a ponta e imprime a configuração exata para seu cliente.

Então, para Claude Code:

claude mcp add --scope user iphone-mirror -- ~/.local/bin/iphone-mirror-mcp

Ou para qualquer outro cliente MCP:

{
  "mcpServers": {
    "iphone-mirror": {
      "command": "/Users/YOU/.local/bin/iphone-mirror-mcp"
    }
  }
}

Pergunte ao seu modelo:

Tire uma captura de tela do meu iPhone e me diga qual aplicativo está aberto.

Ou pegue o pacote .mcpb do último lançamento se seu cliente instala pacotes MCP e você prefere pular o toolchain (veja as ressalvas — ele é assinado ad-hoc, mas não notarizado).

→ Guia completo de início · configuração por cliente

Requisitos

macOS 15+ com iPhone Mirroring, pareado a um iPhone iOS 18+ (próximo, bloqueado, mesma Conta Apple)
Xcode — para as ferramentas xcode_*, device_* e sim_*
Permissão de Acessibilidade e Gravação de Tela, concedida ao aplicativo que inicia o servidor (seu terminal, ou o aplicativo de desktop que hospeda seu cliente) — detalhes

Verifique tudo de uma vez:

iphone-mirror-mcp doctor

Ele testa todas as quatro permissões, captura um quadro real e confirma que o macOS está realmente entregando entrada sintética — em vez de apenas ler flags de permissão. Execute-o antes de suspeitar de qualquer outra coisa.

O que ele pode fazer


Sessão e saúde	`status`, `doctor`, `mirror_launch`, `mirror_restart`
Ver a tela	`screenshot`, `annotated_screenshot` (cada elemento em caixa + numerado), `read_screen` (OCR com centros tocáveis), `find_text`, `find_image`, `record_screen`
Aguardar corretamente	`wait_for_text`, `wait_for_screen_change`, `scroll_to`
Entrada	`tap` (com verificação `expect`), `double_tap`, `long_press`, `swipe`, `drag`, `type_text`, `paste_text` (emoji/CJK via área de transferência), `read_clipboard`, `press_key`, `shake`, `batch`
Navegar	`home`, `app_switcher`, `spotlight`, `launch_app`, `open_url`
Notificações	`notifications`, `notification_click`
Xcode	`xcode_list`, `xcode_build`, `xcode_test`, `xcresult_attachments`
Dispositivos reais	`run_on_iphone`, `devices`, `device_install`, `device_launch`, `device_info`, `device_apps`, `device_uninstall`
Simuladores	`run_on_sim` mais o cinto completo `simctl` — push, GPS, concessões de privacidade, barra de status, aparência, logs, mídia

→ Referência completa de ferramentas — todas as 63, com parâmetros, geradas a partir do catálogo do próprio servidor para que não possa divergir.

Contrato de coordenadas

Cada x/y é uma posição de pixel na captura de tela mais recente, origem no canto superior esquerdo. No momento da entrada, os limites da janela são consultados novamente e o pixel é mapeado proporcionalmente nos limites atuais — então uma janela que foi movida ou redimensionada entre a captura de tela e o toque ainda recebe o toque no lugar certo.

Documentação


Início	Instalação → permissões → primeiro toque
Conectando um cliente	Claude Code, Claude Desktop, Cursor, VS Code, Zed, Codex, Windsurf
Referência de ferramentas	Todas as 63 ferramentas e seus parâmetros
Receitas	Conduzindo um aplicativo, o loop de teste no dispositivo, notificações, agrupamento
Solução de problemas	Sintomas → causas → correções
Arquitetura	Como a entrada realmente chega ao telefone
Limitações	O que isso genuinamente não pode fazer

Limitações conhecidas

Testado, não adivinhado — a lista completa explica o porquê.

Pinça e rotação não podem ser sintetizadas. Gestos de trackpad não percorrem o pipeline CGEvent; um toque de evento não vê nada durante uma pinça física, então não há nada para reproduzir.
Um telefone por vez — a troca de dispositivo não tem menu scriptável.
A sessão pausa sempre que o telefone é desbloqueado ou pego. Design da Apple; retomar exige que ele seja bloqueado novamente.
Sem árvore de acessibilidade — OCR e correspondência de modelos são o modelo de elementos. Face ID, Central de Controle e botões de hardware são inacessíveis, e conteúdo DRM captura preto.

Segurança

Este servidor pode ver e controlar qualquer iPhone com o qual o Mac esteja pareado enquanto o espelhamento estiver ativo. Trate-o como se estivesse entregando seu telefone desbloqueado ao modelo. Execute-o apenas a partir de clientes em que você confia.

O telefone bloqueia a sessão no momento em que é pego ou desbloqueado fisicamente, o que é um verdadeiro interruptor de segurança. paste_text coloca brevemente texto na área de transferência do Mac e restaura o que estava lá; read_clipboard o lê.

Veja SECURITY.md para o modelo de confiança e como relatar uma vulnerabilidade.

Contribuindo

Issues e pull requests são bem-vindos — veja CONTRIBUTING.md.

scripts/run_tests.sh                    # build + unit/protocol tests + CLI smoke
MIRROR_MCP_LIVE=1 scripts/run_tests.sh  # + live tests (real window, capture, input)

Licença

MIT