명령줄

device-mcp-cli는 Device MCP의 명령줄 도구입니다. 앱에서 하거나 AI 에이전트에게 맡기는 일을 터미널, 셸 스크립트, Makefile, CI에서 실행할 수 있습니다. 기기 목록을 보고, 스크린샷을 찍고, 화면을 읽고, 탭하고 입력하고, 앱을 실행하거나 설치하고, 위치를 설정하고, 라이선스를 관리할 수 있습니다.

모든 명령은 JSON으로 응답할 수 있으므로 스크립트에서 텍스트를 파싱하는 대신 jq로 결과를 읽을 수 있습니다.

1. 설치#

• Homebrew: brew install --cask device-mcp로 설치하면 device-mcp-cli가 PATH에 추가됩니다.
• 웹사이트에서 다운로드한 경우: 터미널에서 다음 명령을 한 번 실행해 PATH에 추가하세요.

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

Device MCP가 스스로 업데이트해도 이 링크는 계속 작동합니다. 다음 명령으로 확인하세요.

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

2. 작동 방식#

• 명령은 Device MCP가 실행합니다. 기기 명령은 Mac의 Device MCP 앱으로 전달됩니다. 앱이 실행 중이 아니면 명령이 앱을 열지 먼저 묻습니다. --launch는 묻지 않고 열고(스크립트에서 사용하세요), --no-launch는 절대 열지 않습니다. status, mcp, tools, logs는 앱을 열지 않습니다.
• 기기 지정: --device(또는 -d)에 기기 이름이나 UDID를 지정합니다. 지정하지 않으면 devices select로 고른 기기를, 고른 기기가 없으면 Device MCP에서 선택된 기기를 사용합니다.
• JSON: 어떤 명령에든 --json을 붙이세요. 오류도 JSON으로 출력됩니다.
• 통제권은 사용자에게: 앱 설치와 제거, 링크 열기, 클립보드 읽기나 변경, Build & Run은 AI 에이전트가 할 때와 마찬가지로 Device MCP에서 먼저 사용자에게 묻습니다. 승인을 참고하세요. 기기 페어링 해제와 라이선스 비활성화는 항상 묻습니다.
• Free와 Pro: 모든 명령이 Device MCP Free에서 작동하지만, Build & Run, 앱 설치, 3D 뷰 인스펙터에는 Device MCP Pro가 필요합니다. Free에서는 한 번에 기기 한 대만 미러링합니다.

3. 명령#

<device>는 기기 이름이나 UDID입니다. 모든 명령에 --json을 붙일 수 있고, 기기 명령에는 --device도 붙일 수 있습니다.

기기#

화면#

터치와 키#

앱#

기기 설정#

Device MCP#

그 밖의 기능#

4. 예시#

로그인하고 결과 확인하기#

셸 스크립트나 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
}

모든 기기의 스크린샷 찍기#

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

화면의 요소 탭하기#

elements는 화면의 요소를 ref와 함께 나열합니다. jq로 요소를 찾은 다음 탭하세요.

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

다른 언어와 지역에서 앱 테스트하기#

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

새 시뮬레이터에서 빌드하고 실행하기#

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

버그 화면 기록하기#

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

Mac 설정하기#

CI용 Mac이나 새 팀원의 Mac에서 다음을 실행합니다.

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과 종료 코드#

--json을 붙이면 명령이 JSON 객체 하나를 출력합니다. 예를 들어 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"
    }
  ]
}

기기의 kind는 iphone, ipad, watch, android, simulator, emulator 중 하나입니다. state는 ready, locked, blocked(issue와 fix에 원인과 해결 방법이 담깁니다), connecting, running, shut_down, booting, shutting_down, creating, starting 중 하나입니다.

오류가 나면 {"error": {"code": "…", "message": "…"}}를 출력합니다.

성공한 명령은 0으로 종료합니다.

6. AI 에이전트와 함께 사용하기#

에이전트도 명령줄을 사용할 수 있습니다. 예를 들어 앱의 테스트 스크립트나 CI 단계를 작성하게 할 수 있습니다.

• "내 iPhone에서 로그인하고, 홈 화면이 로드되지 않으면 실패하는 스크립트를 작성해 줘."
• "온보딩의 모든 화면을 스크린샷으로 찍는 CI 단계를 추가해 줘."

에이전트가 실행한 명령은 Agent 탭에 device-mcp-cli로 표시됩니다. 에이전트 활동을 참고하세요.