tanbro/uiautomator2-mcp-server

🇨🇳
중문 설명

행동 강령 (Code of Conduct): 이 프로젝트에 참여할 때는 우리의 행동 강령을 준수해 주세요.

uiautomator2를 사용하여 Android 기기를 제어하기 위한 도구를 제공하는 MCP (Model Context Protocol) 서버입니다.

AI를 사용하여 Android 기기를 자동화하세요: 스크린샷 촬영, 탭/스와이프, 앱 관리, 텍스트 전송 등을 수행할 수 있습니다.

사용자 말하기: "xxx 앱에서 고양이 영상을 검색한 다음, 영상을 재생하고 다음 영상으로 넘겨줘"

AI 자동 수행:

• ✅ 앱 실행 → 검색 탭 클릭 → 키워드 입력 → 검색 실행 → 결과 탭 클릭 -> 다음 영상으로 전환

코딩 없이 자연어로 Android 기기 제어

상세 예시: .skills/douyin-search

• 📱
  멀티 디바이스 (Multi-Device)- 하나의 서버로 여러 대의 휴대폰 제어 - 🔍
  XPath 필터링 (XPath Filtering)- 필요한 UI 요소만 덤프(Dump)하여 토큰을 절약하고 응답 속도 향상 - 🎛️
  도구 필터링 (Tool Filtering)- AI에게 필요한 도구만 보여주어 환각 (Hallucination)을 줄이고 더 나은 결과 도출 - ⚡
  제로 설정 (Zero Setup)- uvx를 사용하여 설치 없이 즉시 실행 - 📦
  독립 실행형 실행 파일 (Standalone Executable)- PyInstaller 또는 Nuitka를 사용하여 독립형 앱으로 번들링 — Python 런타임 불필요 - 🧰
  70개 이상의 도구 (70+ Tools)- 클릭, 스와이프, 타이핑, 앱 관리, 스크린샷 등 필요한 모든 기능 포함 - 🧪
  내장 테스트 (Built-in Testing)- AI 기반 UI 테스트 프레임워크를 기본적으로 포함 - 🔄
  두 가지 모드 (Two Modes)- 로컬용 STDIO, 원격용 HTTP 지원 - 🔒
  클린 코드 (Clean Code)- 타입 힌트(Type hints), 린팅(Linted), 포맷팅(Formatted) 적용 — 확장 용이

시나리오	설명
🧪 자동화 테스트 (Automated Testing)	AI 기반 테스트 프레임워크로 자연어 UI 테스트 실행
⚡ 빠른 프로토타이핑 (Rapid Prototyping)	코드 작성 없이 Android 앱 상호작용을 빠르게 테스트
♿ 접근성 테스트 (Accessibility Testing)	앱의 접근성 기능을 자동으로 검증
📊 상태 모니터링 (Health Monitoring)	주기적인 기기 상태 및 건강 체크
🤖 작업 자동화 (Task Automation)	양식 채우기, 탐색과 같은 반복적인 작업 자동화
🔬 원격 디버깅 (Remote Debugging)	원격으로 UI 계층 구조(Hierarchy)를 조사하고 스크린샷 캡처

graph TD
AI[AI Assistant<br/>Claude/GPT/etc.] --> MCP[MCP Protocol]
MCP --> Server[u2mcp Server]
...

v0.1.3 또는 이전 버전에서 업그레이드하는 경우: 이제 CLI에서 명시적인 서브커맨드 (subcommand)가 필요합니다. 명령어를 다음과 같이 변경하세요:

# 기존 (v0.1.3 및 이전 버전)
u2mcp

다음과 같이 변경:

# 신규 (v0.2.0+)
u2mcp stdio

다른 모든 명령어는 동일하게 유지됩니다 (전송 방식(transport) 서브커맨드만 추가하면 됩니다).

• Python 3.11+
• PATH에 등록된 adb (Android SDK Platform Tools를 통해 설치)
• USB 디버깅 (USB debugging)이 활성화된 Android 기기

💡 도구 선택 권장 사항:

MCP 클라이언트 사용 시 (Claude Desktop, Cursor 등): uvx를 사용하여 패키지를 직접 실행하는 것을 권장합니다.

독립 실행/디버깅: uv, pip, 또는 pipx를 사용할 수 있습니다.
대부분의 사용 사례에서는 uv 설치만으로 충분합니다.

다음은 두 가지 선택적인 강화된 패키지 매니저 (package managers)입니다. 이 중 하나를 선택하여 설치하거나, 원하지 않는 경우 이 단계를 건너뛸 수 있습니다.

• uv 설치 (권장 | 선택 사항)
  대부분의 MCP 클라이언트 (Claude Desktop 등)는 Python MCP 서버를 실행하기 위해 uvx를 사용합니다. uvx는 uv 툴킷의 일부입니다.

왜 uvx를 선택해야 하나요?
uvx는 수동 설치 없이 PyPI에서 Python 패키지를 직접 실행할 수 있습니다. 단순히 uvx package-name을 사용하면 나머지는 자동으로 처리됩니다. 이는 MCP 클라이언트 설정에 완벽하게 부합합니다.

macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell): powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

또는 winget 사용: winget install --id=astral-sh.uv -e

설치 확인:
uv --version uvx --version

• pipx 설치 (선택 사항)
  pipx는 격리된 환경에서 Python CLI 애플리케이션을 설치하고 실행하기 위한 또 다른 도구입니다.

pipx vs uvx:
uvx와 마찬가지로 pipx 또한 pipx run package-name을 통해 패키지를 직접 실행할 수 있습니다. 하지만 일반적으로 uvx가 더 빠르며 MCP 생태계에서 더 흔히 사용됩니다.

macOS / Linux: python3 -m pip install --user pipx python3 -m pipx ensurepath

Windows: python -m pip install --user pipx python -m pipx ensurepath

권장 사항: 설치 없이 PyPI에서 uvx (권장) 또는 pipx run을 사용하여 직접 실행

# uvx로 직접 실행 (권장)
uvx uiautomator2-mcp-server stdio
# 또는 pipx로 직접 실행
...

장기적인 사용을 위해 전역 설치 (global installation)가 필요한 경우, 다음 중 하나를 선택하여 설치할 수 있습니다:

# uv를 사용하여 설치 (tool 방식)
uv tool install uiautomator2-mcp-server
# 또는 pipx로 설치
...

설치 후에는 짧은 별칭(alias)인 u2mcp를 사용할 수 있습니다:

u2mcp stdio

uv, pipx 또는 기타 제3자 패키지 관리자(package manager)를 사용하고 싶지 않다면, Python의 기본 패키지 관리자인 pip를 사용하여 이 소프트웨어를 직접 설치할 수 있습니다:

python -m pip install uiautomator2-mcp-server

패키지 이름에 관한 참고 사항:

CLI 명령은 u2mcp이지만, PyPI 패키지 이름은 uiautomator2-mcp-server입니다. 저희는 v1.0.0에서 이를 u2mcp로 단순화할 계획입니다. 현재는 위에서 언급한 전체 패키지 이름을 사용하여 설치해 주세요.

ℹ️

참고:

pip는 설치 없이 실행하는 것을 지원하지 않습니다.

서버를 독립형 애플리케이션(standalone application)으로 번들링할 수 있습니다 — 대상 기기에 Python 설치가 필요하지 않습니다.

빌드가 빠르며 C 컴파일러가 필요하지 않습니다.

# 1. PyInstaller 설치
uv sync --group pyinstaller
# 2. 빌드
...

이렇게 하면 실행 파일과 모든 런타임(runtime) 파일이 포함된 dist/u2mcp/ 디렉토리가 생성됩니다. 폴더 전체를 휴대용 애플리케이션(portable application)으로 배포하세요.

Python을 C로 컴파일하여 네이티브 .so / .pyd / .dll 바이너리(binaries)를 생성합니다 — 기본적인 수준의 소스 코드 보호를 제공합니다. C/C++ 컴파일러(Windows의 경우 MSVC, Linux/macOS의 경우 GCC/Clang)가 필요합니다.

빌드 옵션은 Nuitka 프로젝트 지침(directives)을 통해 main.py에 사전 구성되어 있습니다:

# 1. Nuitka 설치
uv sync --group nuitka
# 2. 빌드
...

어떤 도구를 사용했든 관계없이:

# STDIO 모드 (로컬 MCP 클라이언트용)
u2mcp stdio
# HTTP 모드 (원격 접속용)
...

참고: 출력물은 Python 런타임과 모든 Python 의존성(dependencies)을 번들링하므로, 대상 기기에 Python, pip 또는 uv가 설치되어 있을 필요는 없습니다. 하지만 adb는 여전히 시스템 PATH에서 사용 가능해야 합니다 (또는 ADBUTILS_ADB_PATH 환경 변수를 통해 설정해야 합니다).

참고: 아래 명령어들은 패키지 설치가 필요한 u2mcp를 사용합니다. 아직 설치하지 않았다면, 대신 uvx uiautomator2-mcp-server ...를 사용하여 직접 실행할 수 있습니다.

MCP 서버는 두 가지 모드로 실행할 수 있습니다:

# 설치된 경우
u2mcp stdio
# 또는 설치 없이 직접 실행
...

이 모드는 표준 입출력 (standard input/output)을 통해 통신하며, 일반적으로 서버 프로세스를 직접 생성하는 MCP 클라이언트에서 사용됩니다.

# 설치된 경우
u2mcp http -H 0.0.0.0 -p 8000 -n
# 또는 설치 없이 직접 실행
...

서버는 http://localhost:8000/mcp (또는 지정된 호스트/포트)에서 대기합니다.

참고: 아래 명령어들은 패키지 설치가 필요한 u2mcp를 사용합니다. 아직 설치하지 않았다면, 대신 uvx uiautomator2-mcp-server ...를 사용하여 직접 실행할 수 있습니다.

u2mcp CLI는 사용 가능한 도구 (tools) 및 태그 (tags)를 탐색하기 위한 여러 유틸리티 명령어를 제공합니다:

# 사용 가능한 모든 도구 목록 표시
u2mcp tools
# 또는 직접 실행
...

참고: 아래 명령어들은 패키지 설치가 필요한 u2mcp를 사용합니다. 직접 실행하는 경우 uvx uiautomator2-mcp-server ...로 대체하세요.

태그 기반 필터링을 사용하여 도구를 선택적으로 노출할 수 있습니다. 이는 LLM (Large Language Model)이 사용할 수 있는 도구의 수를 줄여 성능을 향상시키고 혼란을 방지할 수 있습니다.

# 디바이스 관리 도구만 노출
u2mcp stdio -i device:manage
# 또는 직접 실행
...

시작하기 전에: 이 서버를 사용하도록 MCP 클라이언트 (예: Claude Desktop)를 구성했는지 확인하세요. 자세한 내용은 아래의 'MCP 클라이언트 구성' 섹션을 참조하십시오.

Android 디바이스 연결: USB 디버깅이 활성화된 USB를 통해 연결

• MCP 클라이언트 구성: 이 서버를 사용하도록 구성 (MCP 클라이언트 구성 참조)
• 디바이스 초기화 (최초 1회 필요): "Initialize my Android device"

자동화 시작: "Take a screenshot" "Tap at coordinates 500, 1000" "Swipe up" "Open YouTube app"

단축 옵션 (Short Options):

모든 일반적인 옵션은 편의를 위해 단축 플래그 (short flags)를 지원합니다:

-l / --log-level - 로그 레벨 (log level) 설정
-i

/--include-tags

• 태그별로 도구 포함 (Include tools by tags)

-e

/--exclude-tags

• 태그별로 도구 제외 (Exclude tools by tags)

-H

/--host

• 호스트 주소 설정 (Set host address) (HTTP 모드)

-p

/--port

• 포트 번호 설정 (Set port number) (HTTP 모드)

-t

/--token

• 인증 토큰 설정 (Set authentication token) (HTTP 모드)

-n

/--no-token

• 토큰 검증 비활성화 (Disable token verification) (HTTP 모드)

와일드카드 지원 (Wildcard Support):

--include-tags 및 --exclude-tags 옵션은 와일드카드 패턴 (wildcard patterns)을 지원합니다:

* : 모든 문자 매칭
? : 정확히 한 문자 매칭
device:* : 모든 device:* 태그 매칭
*:mirror : 모든 mirror 태그 매칭 (예: screen:mirror 등)
action:to* : action:touch, action:tool (존재하는 경우) 매칭

사용 가능한 태그 (Available Tags):

태그	설명
device:manage	디바이스 연결, 초기화 및 관리 (Device connection, initialization, and management)
device:info	디바이스 정보 및 상태 (Device information and status)
device:capture	스크린샷 및 UI 계층 구조 (Screenshots and UI hierarchy)
device:shell	쉘 명령 실행 (Shell command execution)
action:touch	클릭 및 탭 동작 (Click and tap actions)
action:gesture	스와이프 및 드래그 제스처 (Swipe and drag gestures)
action:key	물리 키 입력 (Physical key presses)
action:screen	화면 제어 (켜기/끄기) (Screen control (on/off))
app:manage	앱 설치 및 삭제 (Install and uninstall apps)
app:lifecycle	앱 시작 및 종료 (Start and stop apps)
app:info	앱 정보 및 목록 조회 (App information and listing)
app:config	앱 설정 (데이터 삭제, 권한) (App configuration (clear data, permissions))
element:wait	요소/액티비티 대기 (Wait for elements/activities)
element:interact	요소 클릭 및 상호작용 (Click and interact with elements)
element:query	요소 정보 가져오기 (텍스트, 경계) (Get element info (text, bounds))
element:modify	요소 수정 (텍스트 설정) (Modify element (set text))
element:gesture	요소별 제스처 (스와이프, 스크롤) (Element-specific gestures (swipe, scroll))
element:capture	요소 스크린샷 (Element screenshots)
input:text	텍스트 입력 및 삭제 (Text input and clearing)
input:keyboard	키보드 제어 (Keyboard control)
clipboard:read	클립보드 읽기 (Read clipboard)
clipboard:write	클립보드 쓰기 (Write clipboard)
screen:mirror	화면 미러링 (scrcpy) (Screen mirroring (scrcpy))
screen:capture	화면 스크린샷 (Screen screenshots)
util:delay	지연/슬립 유틸리티 (Delay/sleep utility)

MCP Inspector는 AI 클라이언트 없이도 MCP 서버를 테스트하고 디버깅할 수 있는 명령줄 도구 (command-line tool)입니다.

# MCP Inspector 설치
npm install -g @modelcontextprotocol/inspector
# STDIO 모드에서 서버 검사
...

Inspector는 다음 항목들을 표시합니다:

• 사용 가능한 도구 (tools) 및 해당 파라미터 (parameters)
• 서버 리소스 (resources) 및 프롬프트 (prompts)
• 실시간 도구 실행 결과
• 요청/응답 로그 (request/response logs)

Postman은 MCP 서버를 테스트하고 디버깅할 수 있는 네이티브 MCP 지원 기능을 갖추고 있습니다.

• Postman을 열고 새로운 MCP Request를 생성합니다 - 서버 연결 세부 정보를 입력합니다:

STDIO 모드:

Command: u2mcp
Arguments: stdio

HTTP 모드:

URL: http://localhost:8000/mcp

(먼저 서버를 시작하세요: u2mcp http --host 0.0.0.0 --port 8000)

• Load Capabilities를 클릭하여 연결하고 사용 가능한 도구를 탐색합니다 - Tools, Resources, Prompts 탭을 사용하여 서버와 상호작용합니다 - Run을 클릭하여 도구 호출 (tool calls)을 실행하고 응답을 확인합니다.

자세한 내용은 Postman MCP 문서를 참조하세요.

또한 cURL을 사용하여 JSON-RPC 2.0 요청으로 HTTP 엔드포인트 (endpoint)를 테스트할 수 있습니다:

# 1. 먼저 서버를 시작합니다
u2mcp http --host 0.0.0.0 --port 8000
# 2. 다른 터미널에서 MCP 요청을 보냅니다
...

이 MCP 서버는 모든 MCP 호환 클라이언트와 함께 사용할 수 있습니다. 아래는 주요 클라이언트들에 대한 설정 안내입니다.

Claude Desktop 설정 파일에 추가하세요:

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
"mcpServers": {
"android": {
...

패키지를 전역 (globally)으로 설치했다면, 다음과 같이 사용할 수도 있습니다:

{
"mcpServers": {
"android": {
...

Cursor는 네이티브 MCP 지원을 갖춘 AI 기반 코드 에디터입니다.

• Cursor 설정 (Cmd/Ctrl + ,)을 엽니다
• MCP Servers로 이동합니다 - 새 서버를 추가합니다:

{
"mcpServers": {
"android": {
...

Cherry Studio는 완전한 MCP 지원을 제공하는 크로스 플랫폼 (cross-platform) AI 데스크톱 클라이언트입니다. Android 기기 자동화 작업에 이상적입니다.

• Cherry Studio를 다운로드하여 설치합니다
• 설정을 열고 MCP Servers로 이동합니다 - Add Server를 클릭하고 구성합니다:

옵션 A: uvx 사용 (권장)

Command: uvx
Arguments: uiautomator2-mcp-server stdio

옵션 B: 설치된 u2mcp 명령 사용

Command: u2mcp
Arguments: stdio

옵션 C: HTTP 모드
먼저 서버를 시작합니다:

u2mcp http --host 0.0.0.0 --port 8000 --no-token

그 다음 Cherry Studio에서 HTTP 모드를 선택하고 다음을 입력합니다:

URL: http://localhost:8000/mcp

Cherry Studio의 상세한 MCP 설정에 대해서는 공식 문서를 참조하세요.

ChatMCP는 MCP 프로토콜을 구현하는 오픈 소스 AI 채팅 클라이언트입니다. 다양한 LLM (Large Language Model) 제공업체(OpenAI, Claude, Ollama)를 지원합니다.

• ChatMCP를 다운로드하여 설치합니다
• 설정을 열고 MCP Servers로 이동하여 새 서버를 추가합니다:

uvx 사용 (권장)