iphone-use

iphone-use

Deixe agentes de IA usarem seu iPhone real.
Claude Code, Codex ou qualquer cliente MCP lê a tela como texto, toca, digita e desliza em qualquer aplicativo, inclusive os que não possuem API.

English · 简体中文

curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | sh

https://github.com/user-attachments/assets/ee298774-bf3e-4fd0-9a08-481b20904f61

_{Demonstração de 1 minuto, gravações de iPhone real · 中文版}

Por que iphone-use

• Qualquer aplicativo, sem necessidade de API. Funciona em Saúde, aplicativos bancários e de pagamento (até os que escurecem a captura de tela), aplicativos de chat e seu próprio aplicativo em teste.
• USB ou Wi-Fi. Configure o telefone uma vez com um cabo; depois disso, ele pode ser controlado via Wi-Fi por um túnel criptografado.
• iPhones antigos também. iOS 15 ou posterior, sem precisar atualizar o telefone.
• Rápido. Seu próprio executor de dispositivo XCTest lê a tela em cerca de 0,1 s. Um toque que retorna a tela estabilizada leva cerca de 1,9 s (números).
• Resultados honestos. Cada ação informa se foi aplicada, não enviada ou desconhecida, e se uma nova tentativa é segura. Toques em elementos cobertos são recusados, não tratados como concluídos.
• Fluxos reproduzíveis. Uma tarefa concluída uma vez vira um fluxo que é reproduzido em uma única chamada, sem modelo e sem tokens.
• Controle remoto para pessoas também. Controle o telefone você mesmo pelo navegador ou por outro iPhone, na rede local ou de qualquer lugar: tela H.264 ao vivo, mouse e teclado, e pareamento por QR code. Agentes e pessoas compartilham um telefone sem atrapalhar uns aos outros (detalhes).
• Assista ao agente ao vivo. A tela do telefone aparece no painel lateral do host do agente (onde MCP Apps é suportado), em um navegador ou no aplicativo iOS.
• Nada no Mac se move. Nunca toca na tela, cursor ou foco do Mac.

O que você pode pedir

Open Health and tell me how many steps I walked each day this week.
Find the newest message from Mom in WeChat and read it to me.
Collect every transaction on this bank statement page, all the way to the end.
Write this 2,000-word draft into a new note in Notes.
Run my app's login test on the real phone and tell me which step fails.

O agente encontra um aplicativo pelo nome (launch_app {"app": "Health"}) e digita textos longos (até 20.000 caracteres) em uma única etapa. Ele pode ler uma lista em várias páginas e informar se chegou ao fim.

Como funciona

 Claude Code / Codex / any MCP client ──MCP──┐
 scripts and other agents ─────────────HTTP──┤
                                             ▼
                          iphone-use daemon on your Mac ──USB or Wi-Fi──▶ XCTest runner on the iPhone
                                             ▲
 you, in a browser or the iOS app ───────────┘

Um daemon por telefone roda no Mac. Ele lê a tela como uma árvore de acessibilidade (texto, não pixels), envia toques e digitação por um pequeno executor XCTest que instala no telefone e verifica se a tela estabilizou antes de responder. Agentes e pessoas passam pelo mesmo daemon, e um deles segura o telefone por vez.

Instalação

Você precisa de

• Um Mac com macOS 15 ou posterior e Xcode conectado a um Apple ID (um gratuito funciona).
• Um iPhone com iOS 15 ou posterior e Modo de Desenvolvedor ativado (Ajustes → Privacidade e Segurança → Modo de Desenvolvedor).
• Um cabo USB para a primeira configuração. Conecte o iPhone e desbloqueie-o antes de instalar.

O instalador então configura o telefone e mostra um agente abrindo Ajustes e lendo-o. Ele registra o servidor MCP com Claude Code e Codex, e com Cursor e Claude Desktop quando estiverem instalados (IPHONE_USE_NO_CLIENT_SETUP=1 pula esses dois) e abre a página de controle no seu navegador com um login único, para não haver senha para copiar. Se algo estiver faltando, ele informa o que é e como corrigir.

iphone-use status    # is the phone ready for agents?
iphone-use doctor    # what is missing, and how to fix it
iphone-use setup     # set the phone up again (after a new iPhone or Xcode)
iphone-use try       # a harmless check: open Settings, read the screen, go Home
iphone-use login     # sign a browser in again, with a QR code for the iPhone
iphone-use upgrade   # update everything
~/.iphone-use/uninstall.sh --dry-run   # what uninstalling would remove (drop --dry-run to do it)

Ou peça ao seu agente para instalar

Cole isto no Codex ou Claude Code no Mac em que o iPhone está conectado:

Install iphone-use (https://github.com/leeguooooo/iphone-use) on this Mac so you can drive my iPhone.
1. Run: curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | sh
2. Run `iphone-use doctor`. Fix what it reports that can be fixed from the terminal, and run
   `iphone-use setup` when it tells you to.
3. Some steps only I can do: signing in to an Apple ID in Xcode, tapping Trust on the iPhone,
   turning on Developer Mode, unlocking the phone. For those, stop, tell me exactly what to do,
   and wait until I say it is done. Never ask me for a password or a code.
4. Run `iphone-use doctor` again until nothing is missing, then `iphone-use try`.
5. If the phone_* tools are not loaded in this chat yet, tell me to start a new chat.

Plugins para Codex e Claude Code

Cada um adiciona a habilidade e o servidor MCP; eles ainda precisam da instalação acima:

codex plugin marketplace add leeguooooo/iphone-use && codex plugin add iphone-use@iphone-use

No Claude Code:

/plugin marketplace add leeguooooo/iphone-use
/plugin install iphone-use@iphone-use

Controle remoto para pessoas

O mesmo daemon que atende agentes permite que você controle o telefone:

• Pelo navegador. A tela ao vivo chega codificada em H.264 no telefone: resolução nativa a cerca de 50 fps na rede local e um modo mais leve para conexões lentas. Clique para tocar, arraste para deslizar, segure para toque longo, role com a roda ou trackpad. Digite direto no telefone com seu método de entrada, e ⌘V cola. O painel Controles lista os elementos da tela para você tocar por rótulo, e o painel Fluxo grava o que você faz como um fluxo reproduzível. A página segue o idioma do navegador (inglês ou chinês), com um seletor na barra lateral.
• De outro iPhone. O aplicativo iOS nativo (destino mínimo de implantação iOS 15) pareia escaneando um QR code na página do Mac, sem endereço ou senha para digitar. Ele reproduz a tela com o decodificador de hardware e alterna entre seus telefones.
• Telas ocultas da captura. Aplicativos bancários e de pagamento escurecem a captura de tela; lá você vê um wireframe ao vivo dos elementos da tela em vez de uma imagem em branco, e ainda pode tocar através dele.
• De qualquer lugar. Alcance o Mac por um proxy reverso HTTPS autenticado ou uma VPN como Tailscale e controle o telefone fora da sua rede (notas de segurança).
• Sem colisões. Um telefone tem um dono por vez. Enquanto você está no controle, um agente espera ou é informado de quem segura o telefone, e o inverso também é verdadeiro.

Nada no Mac se move enquanto você faz isso: nenhuma janela assume o foco e o cursor permanece no lugar.

Uso a partir de um agente

Um daemon no seu Mac controla o telefone e oferece o mesmo controle em três formas:

• um servidor MCP para Claude Code, Codex, Claude Desktop, Cursor e outros clientes MCP;
• uma API HTTP para agentes e scripts (/agent/*);
• uma página web e um aplicativo iOS nativo para pessoas (controle remoto).

O instalador registra o servidor MCP com Claude Code, Codex, Cursor e Claude Desktop quando presentes (IPHONE_USE_NO_CLIENT_SETUP=1 deixa Cursor e Claude Desktop intactos). Qualquer outro cliente MCP precisa apenas do comando; neste Mac, o servidor encontra o daemon e seu token sozinho:

{
  "mcpServers": {
    "iphone-use": {
      "command": "/Users/YOU/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"
    }
  }
}

Configuração para Cursor, VS Code, Claude Desktop, Gemini CLI, opencode, Windsurf

Use o caminho absoluto (substitua YOU) e mescle a entrada no arquivo; mantenha os servidores já existentes.

• Cursor: ~/.cursor/mcp.json (ou .cursor/mcp.json em um projeto), o bloco mcpServers acima.

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json, o bloco mcpServers acima; saia e reabra o aplicativo.

• Gemini CLI: ~/.gemini/settings.json (ou .gemini/settings.json em um projeto), o bloco mcpServers acima.

• Windsurf / Devin Desktop: ~/.codeium/windsurf/mcp_config.json (versões mais novas: ~/.config/devin/mcp_config.json), o bloco mcpServers acima.

• VS Code / Copilot: .vscode/mcp.json em um workspace, ou MCP: Open User Configuration para todos os workspaces. A chave é servers:

  {
    "servers": {
      "iphone-use": {
        "type": "stdio",
        "command": "/Users/YOU/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"
      }
    }
  }
  

• opencode: ~/.config/opencode/opencode.json (ou opencode.json em um projeto). A chave é mcp e o comando é um array:

  {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
      "iphone-use": {
        "type": "local",
        "command": ["/Users/YOU/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"],
        "enabled": true
      }
    }
  }
  

Ou chame a API HTTP diretamente:

AUTH="Authorization: Bearer $TOKEN"; CTL="X-Phone-Control: 1"
curl -s -H "$AUTH" $HOST/agent/elements                     # the screen as text + a snapshot token
curl -s -H "$AUTH" -H "$CTL" -X POST "$HOST/agent/input?return=delta" \
  -d '{"type":"tap","element":7,"snapshot":"…"}'            # tap, then what changed (~2 s)

Para desenvolvedores de aplicativos e testadores, as mesmas ferramentas também leem os logs e relatórios de falha do telefone, gravam a tela em MP4, instalam um build (.ipa, .app ou um link https), definem uma localização simulada e mantêm notas por aplicativo que os agentes leem ao entrar no aplicativo. IPHONE_USE_MCP_TOOLS=readonly expõe apenas as ferramentas de leitura, e iphone-use-mcp --listen 127.0.0.1:PORT serve MCP por HTTP. Um listener de loopback é acessível apenas pelo mesmo Mac; para um cliente em outra máquina, coloque-o atrás de um túnel autenticado ou escute em outro endereço com IPHONE_USE_MCP_TOKEN definido (é obrigatório fora do loopback).

Sem telefone à mão? Enquanto desenvolve, controle um Simulador iOS da mesma forma (pré-visualização, requer Xcode): iphone-use simulator start "iPhone 16 Pro" compila e inicia tudo, depois aponte o agente para ele com claude mcp add iphone-sim -e IPHONE_USE_INSTANCE=sim -- iphone-use-mcp. Veja Simuladores.

Veja as ferramentas MCP e a referência da API de Agente.

Segurança e privacidade

• Segredos ficam com você. Para logins, senhas e Face ID, o agente para e pede que você termine no telefone. Ele nunca pede a senha ou o código.
• Limites que o agente não pode contornar com conversa. O daemon recusa aplicativos que você bloqueia (IPHONE_USE_BLOCKED_APPS, por exemplo Wallet, Passwords) e limita as ações por tarefa (IPHONE_USE_MAX_ACTIONS), independentemente do que o prompt do agente disser (detalhes).
• Você vê o que ele faz. A página web mostra cada ação sobre a tela ao vivo em palavras simples, por exemplo Tapped “Wi-Fi”. Texto digitado nunca é armazenado, apenas seu comprimento.
• Local por padrão. O daemon escuta em 127.0.0.1:44321 atrás de uma senha, e o executor no telefone aceita apenas solicitações assinadas com um token por inicialização. O caminho LAN iOS 15/16 não é criptografado (segurança).
• Sem telemetria. Este build não envia dados de uso (telemetria · política de privacidade).

Fluxos: faça uma tarefa uma vez, reproduza-a sem modelo

Tarefas repetidas são mantidas como fluxos: scripts revisados por aplicativo que são reproduzidos sem modelo, então não custam tokens. O registro oficial é leeguooooo/iphone-use-flows. Grave um fluxo no painel Fluxo do navegador e publique-o lá com um PR.

Agentes encontram fluxos sozinhos: quando um entra em um aplicativo, a resposta lista os fluxos desse aplicativo. Depois que um agente faz uma tarefa de várias etapas em um aplicativo sem fluxos, ele pergunta se deseja salvar a tarefa como fluxo; o daemon já gravou as etapas como rascunho. O daemon mantém o registro atualizado sozinho (IPHONE_USE_FLOWS_NO_AUTO_UPDATE=1 desativa isso, IPHONE_USE_FLOWS_NO_SUGGEST=1 silencia as sugestões de salvamento).

MCP=~/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp
$MCP flow update                            # sync the registry (sha256-checked)
$MCP flow list                              # what is available
$MCP flow run health/export-all-zh-cn       # replay one; failures say which step and why
$MCP flow draft --out my-task.json          # what you just did on the phone, as a draft flow

Fluxos também criam suítes de teste reexecutáveis ($MCP test suite.yaml, com código de saída pronto para CI) e execuções agendadas que o daemon inicia em uma linha cron ($MCP schedule add): veja Testes e execuções agendadas.

Velocidade

iphone-use controla o telefone por seu próprio executor XCTest (runner/). Ele fala a API HTTP do WebDriverAgent e é construído para velocidade:

• Lê a tela com um único snapshot de acessibilidade de um conjunto fixo de atributos, em vez de percorrer a árvore de elementos atributo por atributo.
• Sintetiza toques diretamente e não espera o aplicativo ficar ocioso antes de agir; o daemon verifica depois que a tela estabilizou.
• É um pequeno aplicativo com um servidor HTTP integrado e stream MJPEG; não há dependências extras no telefone.

Medido no mesmo iPhone 13 via USB, contra agent-device (outubro de 2026):

	executor iphone-use	agent-device
Ler a tela (árvore de acessibilidade)	0,08–0,135 s	~0,7 s
Tocar e esperar a tela estabilizar	1,0 s	2,8–3,3 s

Pela API completa de agente, um toque por rótulo que retorna a mudança estabilizada leva cerca de 1,9 s em um iPhone 17 Pro Max; a versão baseada em WebDriverAgent levou 4,2 s. A visualização ao vivo transmite a 27–28 fps. Cada telefone tem seu próprio daemon e executor, então dois telefones controlados ao mesmo tempo rodam tão rápido quanto um sozinho.

Mais

• Guia completo: navegador e aplicativo iOS, fluxos e o registro de fluxos, Wi-Fi e iOS 15/16, ciclo de vida, configuração, segurança, desenvolvimento.
• Referência da API de Agente · Ferramentas MCP · Arquitetura · Armadilhas de configuração de dispositivo · Executor de dispositivo · Privacidade
• Guia do produto: instalação, configuração MCP, fluxos e comparação.
• Problemas e ideias: Issues no GitHub.

Licença

PolyForm Shield 1.0.0. Este projeto é de código-fonte disponível. Uso não concorrente, modificação e distribuição são permitidos sujeitos à licença; usar o software para fornecer um produto ou serviço concorrente, incluindo um gratuito, é proibido. Veja escopo da licença e avisos de terceiros.

A família *-use

Small, composable CLIs that give an AI agent hands on one real thing. Same shape everywhere: curl … install.sh | sh to install, JSON on stdout, and a companion skill that teaches your agent to drive it — each repo's own README says how to install its skill, since the right way differs per project and per release.

Repo	Gives your agent
chrome-use	A real browser — logged-in sessions, forms, scraping, screenshots
mail-use	Email — read, search, send, triage across Gmail / QQ / 163 / any IMAP
wechat-use	WeChat on macOS — send messages, query contacts and history
discord-use	Discord — messages, channels, forums, webhooks (REST-only, Rust)
cookie-use	Many logged-in accounts per site — capture, switch, apply sessions
profile-use	Your personal profile, safely — fill signup / KYC / checkout forms
bitwarden-use	Bitwarden / Vaultwarden — headless passkey (FIDO2) login
chatgpt-use	Your ChatGPT subscription as a coding-agent backend — no API key
computer-use	The macOS desktop itself
pixcake-use	Read-only PixCake probing — snapshot / diff / SQLite inspection

Autor

Construído por 郭立 (Guo Li / leeguoo) — leeguoo.com · GitHub · X · mais ferramentas na família *-use.