mcp-android-server-python: uiautomator2를 이용한 Android 자동화 MCP (Model Context

이 프로젝트는 uiautomator2를 사용하여 Android 기기를 자동화하기 위한 MCP (Model Context Protocol) 서버를 제공합니다. GitHub Copilot Chat, Claude 또는 Open Interpreter와 같은 AI 에이전트에 쉽게 연결하여 자연어를 통해 Android 기기를 제어할 수 있도록 설계되었습니다.

이 서버는 기능별로 정리된 도구들과 함께 깔끔하고 모듈화된 아키텍처로 리팩토링되었습니다:

mcp-android-server-python/
├── server.py # 메인 서버 (61줄 - 깔끔하고 집중됨)
├── server_original_backup.py # 기존 모놀리식(monolithic) 버전의 백업
...

유지보수성 (Maintainability): 메인 서버를 건드리지 않고도 도구를 쉽게 추가/수정/삭제할 수 있음
조직화 (Organization): 도구들이 기능별로 논리적으로 그룹화됨
테스트 (Testing): 개별 도구 모듈을 별도로 단위 테스트 (unit test) 할 수 있음
재사용성 (Reusability): 도구 모듈을 다른 프로젝트에서 재사용할 수 있음
확장성 (Scalability): 새로운 도구 카테고리를 별도의 모듈로 추가할 수 있음
클린 코드 (Clean Code): 메인 서버가 1321줄에서 61줄로 축소됨

• Python 3.13 이상
• Android Debug Bridge (adb) 설치 및 PATH 설정 완료
• USB 디버깅이 활성화된 연결된 Android 기기
• uiautomator2 호환 Android 기기

스마트 기기 감지 (Smart Device Detection): 사용 가능한 기기를 자동으로 찾아 연결
포괄적인 기기 정보 (Comprehensive Device Info): 시리얼 번호, 해상도, 배터리, WiFi IP, Android 버전 획득
ADB 진단 (ADB Diagnostics): ADB 가용성 및 연결 상태 확인
상태 모니터링 (Health Monitoring): 내장된 서버 상태 체크

앱 탐색 (App Discovery): 모든 설치된 애플리케이션 목록 표시 (시스템 + 사용자 앱)
앱 생명주기 제어 (App Lifecycle Control): 패키지 이름을 통한 앱 시작, 중지, 강제 종료
앱 상태 모니터링 (App State Monitoring): 현재 포그라운드(foreground) 앱 및 액티비티(activity) 추적
데이터 관리 (Data Management): 테스트를 위한 앱 데이터/캐시 삭제

화면 전원 관리 (Screen Power Management): 프로그래밍 방식으로 화면 켜기/끄기
스마트 잠금 해제 (Smart Unlock): 표준 방법을 사용한 자동 화면 잠금 해제
화면 상태 모니터링 (Screen State Monitoring): 화면 활성화 대기 (비동기 (async) 지원)

정밀 상호작용 (Precision Interactions): 텍스트, 리소스 ID (resource ID), 또는 콘텐츠 설명 (content description)을 통한 클릭
고급 제스처 (Advanced Gestures): 롱 클릭 (Long click), 스와이프 (swipe), 드래그 (drag) 작업
텍스트 입력 (Text Input): 선택적 필드 삭제 기능이 포함된 스마트 텍스트 입력
하드웨어 키 (Hardware Keys): 홈 (home), 뒤로 가기 (back), 메뉴 (menu), 볼륨 키 (volume keys) 시뮬레이션

요소 분석 (Element Analysis): 상세한 UI 요소 속성 및 경계 (bounds) 가져오기
화면 캡처 (Screen Capture): 디버깅 및 문서화를 위한 스크린샷 촬영
UI 계층 구조 (UI Hierarchy): 전체 화면 구조를 XML로 내보내기
스마트 대기 (Smart Waiting): 사용자 정의 타임아웃과 함께 요소가 나타날 때까지 대기
스크롤 감지 (Scroll Detection): 긴 목록에서 요소를 찾기 위한 자동 스크롤

토스트 감지 (Toast Detection): 검증을 위한 시스템 토스트 메시지 캡처
액티비티 모니터링 (Activity Monitoring): 특정 Android 액티비티 (activities) 대기
백그라운드 작업 (Background Operations): 시간이 오래 걸리는 작업에 대한 비동기 (async) 지원

다음 용도에 완벽합니다:

• 실제 기기와 상호작용해야 하는 AI 에이전트 (AI agents)
• 원격 기기 제어 설정
• 자동화된 QA 도구
• Android 봇 프레임워크
• UI 테스트 및 자동화
• 기기 관리 및 모니터링

git clone https://github.com/nim444/mcp-android.git
cd mcp-android

# uv (https://github.com/astral-sh/uv) 사용 시
uv venv
source .venv/bin/activate # Windows의 경우: .venv\Scripts\activate

uv pip install

서버는 사용 사례에 따라 두 가지 다른 전송 모드 (transport modes)를 지원합니다:

이것은 Claude Desktop, VS Code 또는 기타 MCP 클라이언트와 같은 AI 에이전트와 통합하기 위한 표준 모드입니다.

# stdio 모드를 사용하려면 server.py를 편집하세요 (기본값은 주석 처리되어 있음)
# stdio 섹션의 주석을 해제하고 http 섹션의 주석을 처리하세요
# 그런 다음 실행하세요:
...

이 모드는 서버를 HTTP API로 실행하며, 웹 애플리케이션, curl 테스트 또는 직접적인 HTTP 호출에 유용합니다.

# 현재 기본 설정 - HTTP 서버로 실행
uv run python server.py
# 서버 사용 가능 주소: http://localhost:8080

server.py를 편집하고

if __name__ == "__main__":

섹션을 수정하세요:

stdio 모드용 (AI 에이전트):

if __name__ == "__main__":
mcp.run(
transport="stdio",
...

HTTP 모드용 (Web API):

if __name__ == "__main__":
mcp.run(
transport="streamable-http",
...

이 서버를 사용하려면 MCP 클라이언트가 필요합니다. Claude Desktop 앱이 MCP 클라이언트의 한 예입니다.

중요: AI 에이전트 (AI agent) 통합을 위해서는 서버를 stdio 모드로 설정해야 합니다 (위의 "옵션 1" 참조).

Claude Desktop에서 이 서버를 사용하는 방법:

• Windows:
  %APPDATA%\Claude\claude_desktop_config.json

• macOS:
  ~/Library/Application Support/Claude/claude_desktop_config.json

{
"mcpServers": {
"mcp-android": {
...

/path/to/mcp-adb 부분을 이 저장소를 클론(clone)한 절대 경로로 교체하세요. 예: /Users/username/Projects/mcp-adb

VS Code의 에이전트 모드 (VS Code 1.99 이상 필요)에서도 이 MCP 서버를 사용할 수 있습니다. 설정 방법은 다음과 같습니다:

• 워크스페이스에 .vscode/mcp.json 파일을 생성합니다:

{
"servers": {
"mcp-android": {
...

/path/to/mcp-adb 부분을 이 저장소를 클론(clone)한 절대 경로로 교체하세요.

설정을 추가한 후, 다음 명령을 사용하여 서버를 관리할 수 있습니다:

• 명령 팔레트 (Command Palette) → MCP: List Servers: 설정된 서버를 확인하고 관리합니다.
• 명령 팔레트 (Command Palette) → MCP: Start Server: 서버를 시작합니다.
• 서버의 도구(tools)들은 VS Code의 에이전트 모드 채팅에서 사용할 수 있습니다.

HTTP 모드(옵션 2)로 실행할 때는 HTTP 요청을 통해 서버와 직접 상호작용할 수 있습니다:

# 서버 실행 여부 확인
curl http://localhost:8080/
# 사용 가능한 도구 목록 (적절한 도구 검색 엔드포인트를 구현해야 합니다)
...

HTTP 모드 활용 사례:

• Android 자동화 기능이 포함된 웹 애플리케이션
• stdio를 사용할 수 없는 테스트 도구
• 다른 서비스와의 직접적인 API 통합
• curl/Postman을 이용한 디버깅 및 개발

이 프로젝트는 기기의 인터페이스 구조를 확인하고 분석할 수 있는 강력한 UI 검사 도구인 uiauto.dev 지원을 포함하고 있습니다.

• UI 검사기(UI inspector) 설치:

uv pip install uiautodev

• 검사기 실행:

uiauto.dev

• 브라우저를 열고 https://uiauto.dev 로 이동하세요.

도구 이름 (Tool Name)	설명 (Description)
mcp_health	MCP 서버가 정상적으로 실행 중인지 확인
get_device_status	전체 기기 상태 및 준비 정보 가져오기
connect_device	Android 기기에 연결하고 기본 정보 가져오기
get_device_info	상세 기기 정보 가져오기: 시리얼 번호, 해상도, 배터리 등
check_adb_and_list_devices	ADB 설치 여부를 확인하고 연결된 기기 목록 표시

도구 이름 (Tool Name)	설명 (Description)
get_installed_apps	버전 및 패키지 정보와 함께 설치된 모든 앱 목록 표시
get_current_app	현재 포그라운드 (foreground)에 있는 앱 정보 가져오기
start_app	패키지 이름을 사용하여 앱 시작
stop_app	패키지 이름을 사용하여 앱 중지
stop_all_apps	현재 실행 중인 모든 앱 중지
clear_app_data	지정된 앱의 사용자 데이터/캐시 삭제

도구 이름 (Tool Name)	설명 (Description)
screen_on	화면 켜기
screen_off	화면 끄기
unlock_screen	화면 잠금 해제 (필요 시 화면을 켜고 스와이프 수행)
wait_for_screen_on	화면이 켜질 때까지 비동기적으로 대기

도구 이름 (Tool Name)	설명 (Description)
press_key	하드웨어 키 누름 시뮬레이션 (예: home, back, menu 등)
click	text, resourceId 또는 description을 통해 요소(element) 탭
long_click	요소(element)를 길게 클릭
send_text	현재 포커스된 필드에 텍스트 입력 (선택 사항으로 입력 전 내용 삭제)
swipe	한 좌표에서 다른 좌표로 스와이프
drag	요소를 특정 화면 위치로 드래그

도구 이름 (Tool Name)	설명 (Description)
get_element_info	UI 요소(element) 정보 가져오기 (텍스트, 경계값(bounds), 클릭 가능 여부 등)
wait_for_element	화면에 요소(element)가 나타날 때까지 대기
scroll_to	주어진 요소(element)가 보일 때까지 스크롤
screenshot	기기에서 스크린샷을 찍고 저장
dump_hierarchy	현재 화면의 UI 계층 구조(hierarchy)를 XML로 덤프 (dump)

도구 이름 (Tool Name)	설명 (Description)
get_toast	화면에 표시된 마지막 토스트 (toast) 메시지를 가져옴
wait_activity	특정 액티비티 (activity)가 나타날 때까지 대기

이 프로젝트는 MIT 라이선스(MIT License) 하에 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.