Phone-Eye 📱👁️

AI 에이전트가 실제 Android 휴대폰을 보고 — 조작할 수 있게 하세요.

코딩 에이전트는 코드를 읽고, 명령을 실행하고, 문서를 탐색할 수 있습니다. 그런데 실제 휴대폰에서 실제 픽셀로 빌드 중인 앱을 볼 수 있을까요? Phone-Eye는 에이전트에게 눈과 손가락을 제공합니다.

phone_look("what's on screen, and where is the login button?")
  → "Login button at (540, 1830) — a green 'Sign in' …"
phone_tap(540, 1830)
phone_look("did the next page load?")

다섯 가지 동사, 프레임워크 없음: 에이전트가 필요에 따라 어떤 워크플로로든 조합할 수 있습니다. 모든 MCP 클라이언트 — Claude Code, Codex, Cursor, dsh 등과 함께 작동합니다.

왜?

휴대폰에서 실행되는 무언가를 빌드하거나 테스트한다면 이런 루프를 잘 알 것입니다: 실제 기기에서 레이아웃이 깨지고, 손으로 스크린샷을 찍고, 화면을 말로 설명하고("설정 아이콘, 오른쪽 위, 계정 항목 옆"), 에이전트와 휴대폰 사이에서 좌표 디코더 역할을 하는 과정입니다. Phone-Eye는 그 루프를 닫습니다 — 에이전트가 이미 코드베이스와 반복 작업을 하듯 기기와도 반복합니다.

두 채널이 융합됩니다:

• 비전 — 비전 모델이 실시간 스크린샷에 대한 자연어 질문에 답합니다(게임 캔버스, 이미지, 픽셀로 표시할 수 있는 모든 것에서 작동).

• UI 트리 — 접근성 트리에 정확한 텍스트와 경계가 있을 때 uiautomator 덤프로 이를 확보합니다.

비전은 플러그인 방식입니다. describe_image(path, question)을 노출하는 모든 MCP 서버가 작동합니다 — 별도 설정 없이 클라우드 GLM 비전을 사용하거나, 로컬 Qwen-VL 엔드포인트를 지정하면 어떤 픽셀도 LAN 밖으로 나가지 않습니다.

Related MCP server: scrcpy-mcp

설치

요구 사항: Python 3.10+, PATH에 adb(platform-tools / android-tools), USB 디버깅이 켜진 휴대폰, 그리고 아무 MCP 비전 서버.

git clone https://github.com/boheastill/phone-eye
cd phone-eye
pip install -r requirements.txt

# env (defaults shown):
export ANDROID_SERIAL=""                      # empty = first adb device; or 192.168.x.x:5555
export PHONE_EYE_VISION_URL="http://127.0.0.1:8102/mcp"  # your vision MCP

클라이언트(stdio)에 연결합니다:

// Claude Code / dsh-mcp-client / any stdio MCP config
{
  "mcpServers": {
    "phone-eye": { "command": "python", "args": ["/path/to/phone-eye/server.py"] }
  }
}

또는 자체 인프라 뒤에서 HTTP 서비스(streamable-http)로 실행하고 http://<host>:8122/mcp를 추가하세요 — docs/fleet.md 참조.

휴대폰 연결(1회)

USB로 한 번 연결하면, 그다음부터는 Wi-Fi로 계속 사용할 수 있습니다:

adb devices                      # USB: accept the debugging prompt on the phone
adb tcpip 5555                   # switch to Wi-Fi mode
adb connect <phone-ip>:5555      # unplug and go

도구

무엇인가 / 아닌가

✔ 에이전트의 눈과 손을 실제 Android 기기 하나에 연결, 기기 내 설치 불필요, 루트 불필요 ✔ 비전 우선(UI 트리가 볼 수 없는 곳에서도 작동), 정밀도를 위한 트리 결합 ✔ 프라이버시 옵션: LAN 전용 모델로 비전 지정 가능

✘ 테스트 프레임워크 아님(DSL/레코더 없음 — 에이전트가 로직) ✘ iOS 아님, 기기 팜 아님(아직) ✘ 사람을 위한 모바일 UI 아님(그건 다른 제품)

상태 및 로드맵

1단계(현재): 다섯 가지 동사, 단일 기기, 플러그인 방식 비전 — 실제 하드웨어(Redmi K40 Gaming / Android 13)에서 엔드투엔드로 검증되었습니다. 지금까지 가장 재미있는 묘기는 USB 디버깅 권한 승인 대화상자를 화면에서 직접 발견하고, 버튼을 읽고, 스스로 "허용"을 탭한 것입니다.

• 2단계: 오프라인 비전 빠른 시작, 다중 기기 주소 지정, 재시도/검증 래퍼

• 그 외: 요청 기반 — 이슈를 열면 큐에서 순위가 올라갑니다.

라이선스

MIT

FAQ

비전 서버? 저는 없는데요. describe_image(path, question)을 제공하는 모든 MCP 서버가 작동합니다. 가장 간편한 클라우드 옵션은 GLM 비전 엔드포인트입니다. 완전 오프라인을 원하면 로컬 Qwen-VL(llama.cpp / Ollama OpenAI 호환 + 20줄 어댑터)을 사용해 모든 픽셀을 LAN에 유지할 수 있습니다.

왜 dsh 네이티브 플러그인이 아닌가요? MCP 우선 방식이라 같은 다섯 가지 동사가 모든 클라이언트에서 작동합니다. dsh 사용자는 @deepseek-ai/dsh-mcp-client 또는 dsh plugin add로 연결할 수 있습니다.

검증된 기기

이 표에 여러분의 기기를 PR로 추가하세요.