AI 에이전트에게 실제 iPhone을 조작시키는 오픈소스 도구, iphone-use

API가 없는 앱은 많습니다. 은행, 결제, 헬스케어, 채팅 등이 그렇습니다. AI 에이전트가 아무리 똑똑해도, 이러한 앱들을 대신 조작할 수는 없었습니다.

iphone-use는 실제 iPhone을 AI 에이전트에게 제공하는 오픈소스 도구입니다 (MIT). 화면을 텍스트로 읽고, 터치(tap), 스와이프(swipe), 입력 등의 동작을 수행하며, 조작이 불가능한 경우에는 명확하게 그렇게 알려줍니다.

• GitHub: https://github.com/leeguooooo/iphone-use
• 2분 데모:

작동 원리 (しくみ)

Mac 상의 데몬이 USB를 통해 iPhone 상의 WebDriverAgent를 구동하여 다음 기능을 제공합니다.

• 에이전트 및 스크립트를 위한 HTTP API (/agent/*)
  • Claude Code 등에서 사용할 수 있는 21가지 도구의 MCP 서버
• 사람을 위한 원격 조작 (브라우저 및 iOS 앱)

에이전트의 1단계 동작

curl -s -H "$AUTH" $HOST/agent/elements
curl -s -H "$AUTH" -H "X-Phone-Control: 1" -X POST "$HOST/agent/input?return=delta" \
-d '{"type":"tap","element":7,"snapshot":"…"}'

각 동작은 '실행됨 / 전송 안 됨 / 알 수 없음'과 함께 재시도할 수 있는지 여부를 반환합니다. 고정 헤더나 키보드에 가려진 요소, 표시되지 않은 요소에 대한 터치는 보내지 않고 거부하며, set_value는 입력한 값을 읽어와 확인합니다.

스크린샷 금지 앱

PayPay 같은 결제 앱은 iOS의 보호 기능으로 화면 캡처가 하얗게 나옵니다. 하지만 접근성 트리(accessibility tree)는 가져올 수 있기 때문에, iphone-use는 버튼이나 문자를 와이어프레임 형태로 그리고 X-Capture-Redacted: 1을 붙여서 반환합니다.

속도와 토큰 절약

모든 응답에는 처리 시간 내역이 포함됩니다. 이를 측정하여, 트리 로딩을 1단계당 1회로 줄였습니다. iPhone 17 Pro Max에서 '터치 후 화면 안정화까지' 시간이 8.5초에서 4.2초로 단축되었고, 콜드 스타트(cold start)는 75초에서 13초로 단축되었습니다. 또한, 화면을 텍스트와 차이점만 반환하는 ?since= 기능과 최대 24단계를 한 번에 보내는 배치 처리(batch)를 통해 토큰도 절약합니다.

한번 수행한 것은 플로우로

한 번의 동작을 flow로 기록하고, 검토된 공식 리포지토리(repository)에 넣으면, 다음부터는 모델 없이 명령어 하나만으로 재생할 수 있습니다 (예: iphone-use-mcp flow run health/export-all-zh-cn)
앱 업데이트로 인해 작동이 멈추면, 어느 단계에서 왜 실패했는지 알려줍니다.

설치

macOS 15 이상, Xcode(무료 Personal Team도 가능), 개발자 모드를 활성화하고 USB로 신뢰된 iPhone이 필요합니다.

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

피드백은 GitHub issues로 부탁드립니다.

Discussion