Linha de comando

O device-mcp-cli é a linha de comando do Device MCP. O que você faz no app, ou pede ao seu agente de IA, você também pode executar no Terminal, em um script de shell, em um Makefile ou em CI: listar seus dispositivos, fazer capturas de tela, ler a tela, tocar e digitar, abrir e instalar apps, definir a localização e gerenciar sua licença.

Todo comando pode responder em JSON, então seus scripts leem o resultado com jq em vez de analisar texto.

1. Instalação#

• Homebrew: brew install --cask device-mcp coloca o device-mcp-cli no seu PATH.
• Baixado do site: execute isto uma vez no Terminal para colocá-lo no seu PATH:

sudo ln -sf "/Applications/Device MCP.app/Contents/MacOS/device-mcp-cli" /usr/local/bin/device-mcp-cli

O link continua funcionando quando o Device MCP se atualiza. Confira com:

device-mcp-cli --version
device-mcp-cli --help                  # every command
device-mcp-cli help apps launch        # one command, with its options

2. Como funciona#

• O Device MCP executa seus comandos. Os comandos de dispositivo vão para o app Device MCP no seu Mac. Se ele não estiver em execução, o comando pergunta antes de abri-lo: --launch o abre sem perguntar (use em scripts), --no-launch nunca o abre. status, mcp, tools e logs nunca o abrem.
• Qual dispositivo: adicione --device (ou -d) com o nome ou o UDID de um dispositivo. Sem ele, os comandos usam o dispositivo que você escolheu com devices select; se não houver, o que está selecionado no Device MCP.
• JSON: adicione --json a qualquer comando. Os erros também vêm em JSON.
• Você no comando: instalar e remover apps, abrir links, ler ou alterar a área de transferência e o Build & Run pedem sua aprovação no Device MCP antes, como acontece com um agente de IA. Veja Aprovações. Desfazer o pareamento de um dispositivo e desativar sua licença sempre pedem confirmação.
• Gratuito e Pro: todos os comandos funcionam no Device MCP Free, exceto o Build & Run, a instalação de apps e o inspetor de views em 3D, que exigem o Device MCP Pro. O Device MCP Free espelha um dispositivo por vez.

3. Comandos#

<device> é o nome ou o UDID de um dispositivo. Todo comando aceita --json; os comandos de dispositivo aceitam --device.

Dispositivos#

A tela#

Toque e teclas#

Apps#

Ajustes do dispositivo#

Device MCP#

Todo o resto#

4. Exemplos#

Faça login e confira o resultado#

Um smoke test do seu app, em um script de shell ou em uma etapa de CI:

set -e
device-mcp-cli apps launch com.example.myapp --launch
device-mcp-cli wait-for "Sign In"
device-mcp-cli type "[email protected]" --field "Email"
device-mcp-cli type - --field "Password" < password.txt
device-mcp-cli tap --text "Sign In"
device-mcp-cli wait-for "Welcome" --timeout 20 || {
  device-mcp-cli screenshot -o failure.png
  exit 1
}

Faça uma captura de tela de cada dispositivo#

device-mcp-cli devices --json |
  jq -r '.devices[] | select(.state == "ready" or .state == "running") | .udid' |
  while read -r udid; do device-mcp-cli screenshot --device "$udid" -o ~/Desktop/; done

Toque em um elemento da tela#

elements lista a tela com as refs. Encontre uma com jq e toque nela:

REF=$(device-mcp-cli elements --json | jq -r '.elements[] | select(.label == "General") | .ref')
device-mcp-cli tap --ref "$REF"

Teste seu app em outro idioma e outro lugar#

device-mcp-cli apps launch com.example.myapp --language fr --locale fr_FR
device-mcp-cli location set 48.8584 2.2945
device-mcp-cli open-url "myapp://map"
device-mcp-cli appearance dark

Compile e execute em um novo simulador#

device-mcp-cli simulators start --model "iPhone 17 Pro" --launch
device-mcp-cli build-and-run ~/Projects/MyApp/MyApp.xcodeproj --scheme MyApp
device-mcp-cli screenshot -o ~/Desktop/myapp.png

Grave um bug#

device-mcp-cli record start
# reproduce the bug on the device
device-mcp-cli record stop

Configure um Mac#

Em um Mac de CI ou no Mac de um novo colega de equipe:

device-mcp-cli license activate --launch < license-key.txt
device-mcp-cli mcp on
device-mcp-cli mcp setup claude
device-mcp-cli status

5. JSON e códigos de saída#

Com --json, um comando imprime um único objeto JSON. Por exemplo, device-mcp-cli devices --json:

{
  "devices" : [
    {
      "connection" : "USB",
      "current" : true,
      "kind" : "iphone",
      "mirroringStopped" : false,
      "model" : "iPhone 17 Pro",
      "name" : "My iPhone",
      "osVersion" : "27.0.1",
      "platform" : "iOS",
      "state" : "ready",
      "udid" : "00008150-000A1B2C3D4E5F60"
    }
  ]
}

O kind de um dispositivo é iphone, ipad, watch, android, simulator ou emulator. O state dele é ready, locked, blocked (com issue e fix dizendo o motivo e o que fazer), connecting, running, shut_down, booting, shutting_down, creating ou starting.

Um erro imprime {"error": {"code": "…", "message": "…"}}:

Um comando bem-sucedido termina com o código 0.

6. Com seu agente de IA#

Seu agente também pode usar a linha de comando, por exemplo, para escrever um script de teste ou uma etapa de CI para o seu app:

• "Escreva um script que faça login no meu iPhone e falhe se a tela inicial não carregar."
• "Adicione uma etapa de CI que faça uma captura de tela de cada tela do onboarding."

Os comandos que seu agente executa aparecem na aba Agent como device-mcp-cli. Veja Atividade do agente.