파이썬 3.13 CI 파이프라인 적용 범위: 90% 코드 스타일: ruff 라이센스: MIT

MCP 안드로이드 에이전트

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

빠른 데모

Related MCP server: Android ADB MCP Server

요구 사항

Python 3.13 이상
Android 디버그 브리지(adb)가 설치되고 PATH에 있음
USB 디버깅이 활성화된 Android 기기 연결
uiautomator2 호환 안드로이드 기기

특징

패키지 이름으로 앱 시작, 중지 및 관리
설치된 앱과 현재 포그라운드 앱 검색
탭, 스와이프, 스크롤, 드래그 및 UI 상호 작용 수행
기기 정보, 화면 해상도, 배터리 상태 등을 확인하세요.
스크린샷이나 마지막 토스트 메시지를 캡처하세요
프로그래밍 방식으로 화면 잠금 해제, 깨우기 또는 절전 모드 해제
앱 데이터를 지우고 활동을 기다리세요
건강 검진 및 adb 진단 도구가 포함되어 있습니다.

사용 사례

다음에 적합합니다:

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

설치

1. 저장소를 복제합니다

지엑스피1

2. 가상 환경 생성 및 활성화

# Using uv (https://github.com/astral-sh/uv) uv venv source .venv/bin/activate # On Windows: .venv\\Scripts\\activate

3. 종속성 설치

uv pip install

서버 실행

옵션 1: uvicorn 사용(권장)

uvicorn server:app --factory --host 0.0.0.0 --port 8000

옵션 2: MCP stdio 사용(AI 에이전트 통합용)

python server.py

용법

이 서버를 사용하려면 MCP 클라이언트가 필요합니다. Claude Desktop 앱은 MCP 클라이언트의 한 예입니다. Claude Desktop에서 이 서버를 사용하려면 다음 단계를 따르세요.

Claude Desktop 구성 파일을 찾으세요

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

mcpServers 섹션에 Android MCP 서버 구성을 추가합니다.

{ "mcpServers": { "mcp-android": { "type": "stdio", "command": "bash", "args": [ "-c", "cd /path/to/mcp-adb && source .venv/bin/activate && python -m server" ] } } }

/path/to/mcp-adb 이 저장소를 복제한 절대 경로로 바꾸세요. 예: /Users/username/Projects/mcp-adb

VS Code와 함께 사용

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

작업 공간에 .vscode/mcp.json 파일을 만듭니다.

{ "servers": { "mcp-android": { "type": "stdio", "command": "bash", "args": [ "-c", "cd /path/to/mcp-adb && source .venv/bin/activate && python -m server" ] } } }

/path/to/mcp-adb 이 저장소를 복제한 절대 경로로 바꾸세요.

구성을 추가한 후에는 다음을 사용하여 서버를 관리할 수 있습니다.

명령 팔레트 → MCP: List Servers
명령 팔레트 → MCP: Start Server
서버 도구는 VS Code의 에이전트 모드 채팅에서 사용할 수 있습니다.

VS코드

UI 검사기

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

UI 검사기를 설치하세요:

uv pip install uiautodev

검사기를 시작합니다.

uiauto.dev

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

사용 가능한 MCP 도구

도구 이름	설명
`mcp_health`	MCP 서버가 정상적으로 실행되고 있는지 확인하세요
`connect_device`	Android 기기에 연결하여 기본 정보를 얻으세요
`get_installed_apps`	버전 및 패키지 정보와 함께 설치된 모든 앱을 나열합니다.
`get_current_app`	현재 포그라운드에 있는 앱에 대한 정보를 가져옵니다.
`start_app`	패키지 이름으로 앱 시작
`stop_app`	패키지 이름으로 앱 중지
`stop_all_apps`	현재 실행 중인 모든 앱을 중지합니다.
`screen_on`	화면을 켜다
`screen_off`	화면을 끄세요
`get_device_info`	자세한 장치 정보를 확인하세요: 일련번호, 해상도, 배터리 등.
`press_key`	하드웨어 키 누름 시뮬레이션(예: `home` , `back` , `menu` 등)
`unlock_screen`	화면 잠금 해제(필요한 경우 켜고 스와이프)
`check_adb`	ADB가 설치되어 있는지 확인하고 연결된 장치를 나열하세요.
`wait_for_screen_on`	화면이 켜질 때까지 비동기적으로 대기합니다.
`click`	`text` , `resourceId` 또는 `description` 통해 요소를 탭합니다.
`long_click`	요소를 길게 클릭합니다
`send_text`	현재 포커스가 맞춰진 필드에 텍스트를 입력합니다(선택적으로 그 전에 지우기)
`get_element_info`	UI 요소(텍스트, 경계, 클릭 가능 요소 등)에 대한 정보를 얻으세요.
`swipe`	한 좌표에서 다른 좌표로 스와이프
`wait_for_element`	화면에 요소가 나타날 때까지 기다리세요
`screenshot`	기기에서 스크린샷을 찍고 저장합니다.
`scroll_to`	주어진 요소가 표시될 때까지 스크롤합니다.
`drag`	요소를 특정 화면 위치로 드래그합니다.
`get_toast`	화면에 표시된 마지막 토스트 메시지를 가져옵니다.
`clear_app_data`	지정된 앱의 사용자 데이터/캐시 지우기
`wait_activity`	특정 활동이 나타날 때까지 기다리세요
`dump_hierarchy`	현재 화면의 UI 계층을 XML로 덤프합니다.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

MCP Android Agent