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

MCP 안드로이드 에이전트

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

빠른 데모

요구 사항

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 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

This server cannot be installed

security - not tested

license - not tested

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

AI 에이전트가 자연어를 통해 Android 기기를 제어하고 자동화할 수 있도록 하는 모델 컨텍스트 프로토콜 서버로, 앱 관리, UI 상호작용, 기기 모니터링과 같은 작업을 지원합니다.

Related MCP Servers

DroidMind
hyperb1iss
A
security
-
license
A
quality
A Model Context Protocol (MCP) server that enables AI assistants to control and interact with Android devices, allowing for device management, app debugging, system analysis, and UI automation through natural language commands.
Last updated -
8
243
Apache 2.0
Android ADB MCP Server
landicefu
-
security
-
license
-
quality
A Model Context Protocol server that enables AI assistants to interact with Android devices through ADB, allowing for automated device management, app installation, file transfers, and screenshot capture.
Last updated -
53
27
ISC License
SupaUI MCP Server
buoooou
A
security
-
license
A
quality
A Model Context Protocol server that enables AI agents to generate, fetch, and manage UI components through natural language interactions.
Last updated -
3
21
6
Mobile Next MCP Serverofficial
mobile-next
A
security
-
license
A
quality
A Model Context Protocol server that enables scalable mobile automation through a platform-agnostic interface for iOS and Android devices, allowing agents and LLMs to interact with mobile applications using accessibility snapshots or coordinate-based interactions.
Last updated -
17
4,254
2,305
Apache 2.0

View all related MCP servers

MCP Android Agent