Oh My Phone Use

Ferramentas MCP para controle real de tela de iPhone/iPad via um acessório Bluetooth ESP32 e um Mac, com um modo de firmware separado para chamadas telefônicas.

GitHub
10

Documentação

Oh My Phone Use

Deixe um agente de IA usar um iPhone ou iPad real: veja a tela, toque, digite e role, e faça ligações telefônicas que falam e ouvem em seu nome.

Uma pequena placa ESP32 é as mãos do agente. Ela atua como mouse e teclado Bluetooth para o telefone e como unidade de viva-voz Bluetooth (kit veicular) para chamadas. Um aplicativo no telefone compartilha a tela. Sem jailbreak e sem APIs privadas: o telefone vê apenas um acessório Bluetooth comum.

Duas maneiras de usar

  1. Com seu agente (funciona hoje): Claude ou qualquer outro cliente MCP conecta-se a um servidor MCP no seu Mac e obtém ferramentas de controle de tela e ferramentas de chamadas telefônicas, além de uma habilidade que ensina como usá-las com segurança.
  2. Aplicativo de telefone autônomo (planejado): o aplicativo no telefone controla o telefone e realiza chamadas por conta própria, sem um Mac. Veja Roadmap.
                         ┌─────────────── Mac ───────────────┐
Agent (Claude, …) ──MCP──▶ MCP server ─┬─▶ control server ◀──┼── WebSocket ── phone app (screen sharing)
                         │             └─▶ phone service ────┼── USB serial ──┐            │
                         └───────────────────────────────────┘                │       HTTP over Wi-Fi
                                                                              ▼            ▼
                                                     iPhone / iPad ◀── Bluetooth ── ESP32 board
                                                     (mouse + keyboard, hands-free calls)

Caso de uso 1: Deixe um agente controlar seu telefone

Deixe seu agente ver a tela do seu telefone, tocar, digitar e rolar para executar tarefas em seus aplicativos. O exemplo abaixo mostra o Codex usando a habilidade Oh My Phone Use para enviar um convite para jantar pelo aplicativo Mensagens do iPhone.

Codex sending a dinner invitation to John, alongside the iPhone showing the sent message and the ESP32 board

As imagens são combinadas para apresentação.

Caso de uso 2: Deixe um agente fazer chamadas telefônicas

Dê ao seu agente um número de telefone e uma tarefa. Ele pode ligar pelo seu iPhone, falar e ouvir em seu nome, enquanto você acompanha a conversa na página de escuta ao vivo. O exemplo abaixo mostra uma chamada perguntando ao John a que horas ele sai do trabalho, com o iPhone roteando o áudio da chamada pelo ESP32.

Codex placing a call alongside the live listening page and an iPhone using Oh My Phone Use Audio

As imagens são combinadas para apresentação, com o número de telefone e detalhes pessoais ocultos. A captura de tela mostra uma chamada em andamento; as transcrições podem ser imprecisas.

Status

A estrutura do repositório e as APIs estão atualmente instáveis e podem mudar sem compatibilidade retroativa conforme o projeto evolui.

CapacidadeEstado
Controle de tela via MCP (get_screen, issue_actions)Funciona com o build de firmware padrão; calibração do ponteiro no aplicativo
Chamadas telefônicas via MCP (phone_*)Funciona com o build de firmware HFP: discar ou anexar, turnos de fala (macOS say), transcrição local (whisper.cpp), desligar, resultados salvos
Ambos ao mesmo tempo em uma placaAinda não: o ESP32-PICO-V3 não tem RAM suficiente para Wi-Fi + HFP + BLE HID juntos
Aplicativo autônomoPlanejado

Início rápido (com seu agente)

Você precisa de um ESP32-PICO-KIT-1 (ESP32 clássico), um Mac com ESP-IDF v6.1, Python 3.10+, Node.js 20+, Xcode completo e uma equipe de assinatura da Apple, e um iPhone ou iPad rodando iOS/iPadOS 17 ou posterior. Este é o alvo de implantação do aplicativo, não uma afirmação de que todas as versões de sistema operacional suportadas foram testadas; veja as notas de teste de dispositivos. O caminho atual de fala para chamadas telefônicas usa macOS say; Linux e Windows não são validados para a configuração completa. Controle de tela e chamadas exigem builds de firmware diferentes na placa atual, conforme descrito em Status.

  1. Firmware: compile e grave, pareie o telefone via Bluetooth e, em um iPhone, ative o AssistiveTouch (firmware/README.md):

    idf.py -C firmware set-target esp32
idf.py -C firmware build
idf.py -C firmware -p /dev/cu.usbserial-XXXXX -b 230400 flash

  2. Servidor de controle e servidor MCP (o primeiro início cria o segredo do dispositivo de entrada):

    npm ci --prefix host/control_server
npm run start:background --prefix host/control_server
npm run calibration:background --prefix host/control_server
npm run mcp:background --prefix host/control_server        # http://127.0.0.1:8780/mcp

  3. Provisione a placa com esse segredo e a rede Wi-Fi que o telefone usa; o script imprime o endereço da placa (phoneuse.local ou um IP):

    python3 -m venv .venv && .venv/bin/pip install -r host/tools/requirements.txt
bash host/tools/provision.sh /dev/cu.usbserial-XXXXX "Wi-Fi SSID" "password"

  4. Instale o aplicativo (ios/README.md): copie ios/.signing.env.example para ios/.signing.env, defina seu ID de equipe e um ID de pacote único, então

    bash ios/scripts/build.sh -allowProvisioningUpdates
xcrun devicectl list devices
bash ios/scripts/install.sh YOUR_DEVICE_ID

    No aplicativo, insira http://phoneuse.local como a ferramenta de entrada, ws://YOUR_MAC_IP:8765/device como o servidor de controle, execute a calibração do ponteiro, toque em Iniciar Sessão e confirme Iniciar Transmissão.

  5. Conecte seu agente ao servidor MCP e dê a ele a habilidade. Para Claude Code:

    claude mcp add --transport http oh-my-phone-use http://127.0.0.1:8780/mcp
cp -R skills/oh-my-phone-use ~/.claude/skills/

    Peça para ele fazer algo no telefone. Verificação rápida sem um agente: node host/control_server/client.js screen salva uma captura de tela em host/control_server/.state/.

Chamadas telefônicas precisam do build de firmware HFP e do serviço de telefone no Mac; veja host/README.md. Quando uma etapa não se comporta como descrito, docs/troubleshooting.md lista os sintomas e suas correções.

O servidor MCP e o servidor de controle não têm autenticação: mantenha-os em loopback ou em uma rede privada (SECURITY.md). Uma chamada alcança uma pessoa real: a habilidade faz o agente discar apenas números que você forneceu, apresentar-se usando seu nome preferido ou o contexto disponível, explicar que as respostas são transcritas para você e confirmar o que ouviu.

Estrutura do repositório

CaminhoO que é
firmware/Firmware ESP-IDF: mouse + teclado BLE HID, ferramenta de entrada Wi-Fi, unidade viva-voz HFP, testes de host
host/Lado Mac: servidor MCP unificado e servidor de controle (host/control_server/, Node), serviço de telefone e ferramentas seriais (host/tools/, Python)
ios/Aplicativo iPhone/iPad: compartilhamento de tela (ReplayKit), sessões, calibração do ponteiro, encaminha entrada para a placa
skills/oh-my-phone-use/Habilidade para agentes que usam o servidor MCP
docs/Protocolo HTTP da ferramenta de entrada entre o aplicativo, o servidor de controle e a placa; solução de problemas por sintoma. Os outros protocolos são documentados ao lado de suas implementações: serial em firmware/README.md, servidor de controle em host/control_server/PROTOCOL.md
AGENTS.mdConvenções para agentes de codificação e contribuidores que alteram este repositório (um por componente também)

Desenvolvimento

make -C firmware/test/host test                           # firmware logic, no hardware
npm test --prefix host/control_server                     # control server, MCP server, calibration
.venv/bin/python -m unittest discover -s host/test/phone    # phone service, simulated board
bash ios/scripts/test_relay.sh                            # app relay against the control server
bash ios/scripts/test_frames.sh                           # fresh-frame selection
bash ios/scripts/test_setup.sh                            # setup-step status
bash ios/scripts/test_session_launch.sh                   # Start Session intent hand-off
bash ios/scripts/test_calibration_click.sh                # calibration click policy

Execute estes comandos a partir da raiz do repositório após instalar as dependências Node e Python acima. Os scripts de harness Swift exigem um Mac com Apple Silicon rodando macOS 14 ou posterior, ferramentas de linha de comando do Xcode e Node.js 20+; quatro scripts atualmente compilam para arm64-apple-macosx14.0. Eles usam peers simulados e não precisam de telefone, placa ou credenciais de assinatura. A suíte somente Node pula o teste de relay nativo; test_relay.sh compila o harness Swift e executa esse teste também. Esses testes não substituem um build do aplicativo iOS ou o teste de aceitação de hardware do firmware.

Roadmap

  • Chamadas e controle de tela juntos: um módulo ESP32 com PSRAM (por exemplo, ESP32-WROVER; o ESP32-S3/C3 não tem Bluetooth Clássico e não pode fazer HFP) para executar Wi-Fi, HFP e BLE HID ao mesmo tempo.
  • Controle de chamadas e áudio via Wi-Fi: um protocolo de rede na placa para chamadas, substituindo o link serial USB, para que o Mac e o aplicativo do telefone usem a mesma API da placa.
  • Aplicativo autônomo: o loop do agente, controle de tela e chamadas no aplicativo do telefone, compartilhando vetores de teste com o compilador de ações e a calibração do servidor de controle.
  • Migração para Rust: migrar o servidor de controle Node.js e o servidor MCP em host/control_server/, e as ferramentas Python e o serviço de telefone em host/tools/, para Rust.

Créditos e licença

O design do controle de tela, o aplicativo do telefone e o servidor de controle vêm de jamiepinheiro/ipad_computer_use (MIT), onde um Seeed XIAO RP2040 USB é a ferramenta de entrada; este projeto o substitui pelo ESP32 e mantém as partes que precisa. THIRD_PARTY.md lista os arquivos derivados e mantém o aviso de direitos autorais upstream. A tag upstream-ac07704 marca o commit que importou o snapshot upstream.

Oh My Phone Use é lançado sob a Licença MIT.