Codex Android MCP

중국어 간체

adb를 통해 Codex가 Android 에뮬레이터를 검사, 테스트, 제어할 수 있게 해주는 로컬 우선(local-first) MCP 서버입니다. STDIO를 통해 엄격하고 타입이 지정된 도구를 노출하며, 스크린샷을 네이티브 MCP 이미지로 반환하고, 물리적 기기와 Gradle 실행은 명시적 시작 정책이 있어야만 허용됩니다.

이 프로젝트는 독립적인 커뮤니티 프로젝트로, OpenAI, DeepSeek, Google과 제휴하거나 보증을 받은 프로젝트가 아닙니다. Android 구현은 ZSeven-W/dsh-android를 MIT 라이선스에 따라 파생한 것이며, DSH/Cordis 등록 및 웹 패널은 공식 MCP TypeScript SDK로 대체되었습니다.

dsh-android에서 변경된 사항

• Codex Desktop, CLI, IDE 클라이언트용 네이티브 MCP STDIO 서버

• serveStdio를 통한 최신 2026년대 MCP 및 2025년 레거시 프로토콜 호환

• 스크린샷이 ImageContent로 반환되며, 인코딩된 후 임시 PNG 파일은 삭제됩니다

• 기본값은 에뮬레이터 전용이며, 물리 기기를 사용하려면 시작 시 두 가지 승인(opt-in)과 모든 호출에서 해당 기기의 정확한 시리얼이 필요합니다

• android_build_run은 기본적으로 제공되지 않으며, 활성화하려면 신뢰할 수 있는 정식 프로젝트 루트가 필요합니다

• 엄격한 JSON 스키마, 패키지/시리얼/경로 검증, 크기 제한 출력, 리터럴 기반 로그 필터링, 취소(cancellation) 지원, 보수적 도구 주석을 제공합니다

• 원시 adb, 셸, 임의 명령, HTTP, 실시간 DSH 사이드바이 제공되지 않습니다

Related MCP server: adb-mcp-server

요구 사항

• Node.js 20.11 이상

• Android SDK Platform-Tools(adb). Android Studio의 SDK Manager 또는 Google의 Platform-Tools 패키지로 설치하세요

• 일회용 Android 에뮬레이터를 강력히 권장합니다

• Android 에뮬레이터 실행기는 선택 사항이며, android_boot 가 AVD 이름을 받을 때만 필요합니다

• OCR 도구는 현재 macOS Apple Vision 환경이 필요합니다. OCR이 아닌 모든 도구는 크로스 플랫폼이며 build/run은 명시적 선택 동의가 필요한 기능입니다

adb나 에뮬레이터 바이너리는 번들링되거나 다운로드되지 않습니다.

Codex에 설치하기

git clone https://github.com/zifanersuotang/codex-android-mcp.git
cd codex-android-mcp
npm ci
npm run build
codex mcp add android -- node C:/absolute/path/to/codex-android-mcp/lib/index.js

Codex Desktop과 CLI는 MCP 구성을 서로 공유합니다. 그러므로 명시적으로 동일한 설정을 구성하려면 다음과 같이 입력합니다.

[mcp_servers.android]
command = "node"
args = ["C:/absolute/path/to/codex-android-mcp/lib/index.js"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "writes"

[mcp_servers.android.env]
ANDROID_MCP_ALLOWED_SERIALS = "emulator-5554"

구성을 변경한 후 Codex를 다시 시작하세요. 연결 확인을 위해 Codex에 “Android 기기 목록을 나열해 줘”라고 요청하세요. 쓰기 도구 승인을 허용 상태로 유지하세요. MCP 도구 어노테이션은 사용 편의를 위한 힌트일 뿐, 권한 인증 경계로 간주해서는 안 됩니다.

보안 정책

안전한 기본 설정은 19개 도구를 노출하며 표준 로컬 emulator-<port> 대상만 허용합니다. 네트워크 및 타사 에뮬레이터 시리얼은 물리 기기 정책을 따릅니다. 호출 시 실행 직전에 정확한 대상을 다시 탐색·승인하며, 승인되지 않은 물리/네트워크 기기는 android_devices에서 제외됩니다.

전용 테스트 폰을 쓸 때의 물리 기기 설정 예시:

[mcp_servers.android.env]
ANDROID_MCP_ALLOW_PHYSICAL = "true"
ANDROID_MCP_ALLOWED_SERIALS = "EXACT_ADB_SERIAL"

위 프로필은 개인 폰이나 개인용 계정에는 사용하지 마세요. USB 디버깅 승인은 폰이 이 PC를 신뢰한다는 뜻이지 모델(기계)의 행동을 허가하는 것은 아닙니다.

하나의 신뢰할 수 있는 프로젝트에 대한 빌드/실행 설정 예시:

[mcp_servers.android.env]
ANDROID_MCP_ALLOW_BUILD_RUN = "true"
ANDROID_MCP_ALLOWED_PROJECT_ROOTS = "C:/work/MyTrustedApp"
ANDROID_MCP_ALLOWED_SERIALS = "emulator-5554"

Gradle 설정과 빌드 스크립트는 실제로 호스트 코드를 실행합니다. 경로 허용 목록은 안전한 센드박스가 아닙니다. 신뢰할 수 있는 코드에만 활성화하고, 신뢰할 수 없는 프로젝트는 자격증명이 없는 VM이나 컨테이너를 사용하세요.

물리 기기나 빌드/실행을 활성화하기 전에 보안 모델과 보안 정책을 먼저 확인하세요.

도구

기기 화면, UI 트리, OCR, 로그, 앱 이름, 기기 내 파일은 신뢰할 수 없는 데이터입니다. 기기가 권한을 부여하거나 Codex가 다른 도구를 호출하도록 유도하지 못하게 하세요. 서버를 통해 비밀번호, 일회용 인증 코드, 결제 정보, 개인 대화내용, 또는 계정 삭제 확인을 입력하지 마세요.

일반적인 작업 흐름

1. android_devices

2. android_screenshot 또는 android_ui_tree

3. 정확한 대상을 확인하고, 애매하면 중단합니다.

4. 승인 게이트가 있는 상호작용 도구로 하나의 행위를 합니다.

5. 다음 작업 전에 반환되는 스크린샷이나 로그를 미리 확인합니다.

MCP는 dsh-android의 상주형 라이브 사이드바를 구현하지 않습니다. android_boot가 좌표 매핑에 쓸 내부 프레임 소스를 준비하므로, Codex나 사용자가 화면을 확인할 필요가 있을 때마다 android_screenshot을 호출합니다.

개발

npm ci
npm run typecheck
npm test
npm pack --dry-run

테스트 스위트엔 정책 단위 테스트, 레거시/최신 프로토콜 모드의 실제 STDIO 클라이언트 실행, 메모리 내 MCP 이미지 라운드트립, fake-ADB 훈련(스모크) 테스트, 크기 제한 로그 테스트, UI 트리 픽스처, OCR 저하 검증이 포함됩니다. npm run test:device 테스트는 선택 사항이며 반드시 일회용 팍 에뮬레이터만 대상으로 해야 합니다.

라이선스 및 저작자 표기

MIT. 원본 dsh-android의 저작권과 라이선스는 LICENSE에 유지되고 있고, 상세한 출처 이력은 THIRD_PARTY_NOTICES에 있습니다.