ARTEMIS - 자연어로 안드로이드 QA자동화 (Gemini + Claude Code MCP 연동)

예전에 Appium으로 QA 자동화를 적용해본 적이 있는데, 이번에 Google에서 자연어 한 줄로 안드로이드 기기를 조작하는 오픈소스 ARTEMIS를 공개해서 실기기에 직접 붙여봤습니다. 설치하면서 막혔던 부분과 Claude Code에 MCP로 연결하는 방법까지 정리해봤어요.

 

ARTEMIS란?

ARTEMIS는 Google이 Apache-2.0 라이선스로 공개한 안드로이드 자동화 에이전트입니다. "설정 열고 배터리 잔량 알려줘" 같은 자연어 지시를 주면, LLM이 화면을 보고 탭/스와이프/입력을 스스로 판단해서 실기기나 에뮬레이터에서 실행합니다.

💡 Appium처럼 요소 ID를 찾아 스크립트를 짜는 방식이 아니라, LLM이 매 단계 스크린샷 + UI 계층(XML)을 보고 다음 행동을 결정하는 방식입니다.

 

ARTEMIS의 특징

자연어로 테스트	스크립트 작성 없이 문장으로 지시
다양한 사용 방식	웹 콘솔, CLI, MCP 서버, Python SDK 제공
실기기 / 에뮬레이터	ADB로 연결된 기기라면 모두 사용 가능
실행 기록(Trace)	단계별 화면, 판단 근거, 리플레이를 대시보드에서 확인
LLM 선택	Gemini 기본, OpenAI / Anthropic / OpenRouter 등도 키 설정 가능

 

Appium과 비교

구분	Appium	ARTEMIS
테스트 작성	Kotlin/Java 등 코드로 작성	자연어 한 줄
요소 탐색	contentDescription, id 등 식별자 필요	LLM이 화면을 보고 판단
결과 재현성	높음 (항상 같은 동작)	모델에 따라 달라질 수 있음
비용	무료	LLM API 토큰 사용

 

사전 준비

• USB 디버깅이 켜진 안드로이드 기기 또는 에뮬레이터
• Python 3.12 이상 (uv가 자동으로 설치해줍니다)
• LLM API 키 1개 이상 (Gemini 키는 Google AI Studio에서 발급)
• (선택) scrcpy, ffmpeg → 화면 스트리밍, 녹화용

 

설치하기 (macOS 기준)

1. 레포 클론 & 실행 스크립트

git clone https://github.com/google/artemis.git
cd artemis
./start.sh

start.sh가 uv 설치, Python 의존성 설치, .env 생성, 웹 콘솔 실행까지 한 번에 해줍니다. Homebrew가 있으면 adb, scrcpy, ffmpeg도 같이 설치해줘요.

2. API 키 설정

open -e .env   # 텍스트 편집기로 열기

# .env
GEMINI_API_KEY=발급받은_키
ADB_DEVICE_SERIAL=기기_시리얼   # adb devices 로 확인
ARTEMIS_HELPER_AUTO_INSTALL=true
ARTEMIS_KEEP_DEVICE_AWAKE=true

💡 .env 안에 OCR_API_KEY 항목이 따로 있는데, 이건 Google Cloud Vision용입니다. Gemini 키는 꼭 GEMINI_API_KEY에 넣어야 해요. (저는 처음에 엉뚱한 줄에 넣어서 키가 없다고 나왔습니다..)

3. 상태 점검

uv run artemis doctor

Python, API 키, 기기 연결, 녹화 도구 등을 한 번에 점검해주고, 막히는 항목이 있으면 해결 방법까지 알려줍니다. 기기가 잠금 화면이면 실행이 안 되니 잠금을 풀고 홈 화면에 두면 됩니다.

 

실행하기

CLI

uv run artemis run "설정 앱을 열고 배터리 메뉴에서 현재 배터리 잔량을 알려줘" --profile flash

웹 콘솔

uv run artemis ui   # http://localhost:8000

• flash 프로필: 빠르게 반응형으로 실행
• pro 프로필: 계획 → 실행 → 검증 단계를 거쳐 더 꼼꼼하게 실행

첫 실행 시 기기에 Artemis Accessibility Helper 앱이 자동으로 설치됩니다. 화면 구조를 읽어오는 접근성 서비스이고, 필요 없어지면 uv run artemis helper uninstall로 지울 수 있어요.

실행이 끝나면 앱에서 찾은 배터리 잔량을 정확히 답해줬고, adb로 확인한 값과도 같았습니다.

 

 

 

설치하면서 겪은 트러블슈팅

1. pyarrow 빌드 실패 (cmake not found)

uv가 최신 Python(3.15)을 잡으면서 pyarrow의 미리 빌드된 wheel이 없어 소스 빌드를 시도하다 실패했습니다. Python 버전을 3.12로 고정하면 해결됩니다.

rm -rf .venv
uv python pin 3.12
uv sync

2. LLM call timed out after 180 seconds (504)

기본 모델인 gemini-3.8-flash가 Gemini 서버에서 504(DEADLINE_EXCEEDED)를 계속 반환해서 작업이 실패했습니다. 직접 호출해보니 짧은 요청에도 응답이 매우 느렸어요. 예비 모델인 gemini-3.7-flash는 신규 사용자에게 막혀 있어서(404) 쓸 수 없었고, config/artemis.jsonc의 기본 모델을 gemini-3.5-flash-lite로 바꾸니 바로 성공했습니다.

// config/artemis.jsonc
"default": {
  "provider": "google",
  "model": "gemini-3.5-flash-lite",
  ...
}

💡 설정을 바꾼 뒤에는 uv run artemis restart로 데몬을 재시작해야 반영됩니다. flash-lite는 가벼운 모델이라 복잡한 시나리오에서는 정확도가 떨어질 수 있어요.

 

Claude Code에 MCP로 연결하기

ARTEMIS는 MCP 서버를 제공해서 Claude Code, Cursor 같은 AI 코딩 도구에서 바로 호출할 수 있습니다.

uv run artemis mcp --install claude

위 명령 하나로 ~/.claude.json에 MCP 서버가 등록되고, ~/.claude/rules/artemis.md에 테스트 규칙이 설치됩니다. 새 세션을 열면 아래 도구들을 사용할 수 있어요.

• mobile_run_task
  자연어로 작업 실행
• mobile_get_device_state
  스크린샷, 화면 계층 확인
• mobile_inspect_trace
  실행 기록 분석
• mobile_manage_task
  작업 상태 확인, 중단, 추가 지시
• mobile_diagnose
  환경 점검

웹 콘솔 / CLI / MCP 차이

셋 다 같은 ARTEMIS 데몬에 작업을 넣는 입구만 다릅니다. 실제로 폰을 조작하는 건 ARTEMIS 내부의 LLM(Gemini)이고, MCP로 연결하면 Claude가 지시를 작성하고 결과를 해석하는 역할을 맡게 됩니다. 실행 기록도 공유돼서 MCP로 돌린 작업도 웹 콘솔에서 리플레이로 볼 수 있어요.

 

토큰 사용량

• Gemini
  매 단계마다 스크린샷 + XML을 보내기 때문에 단계 수만큼 쌓입니다. 제가 돌린 작업은 1회 호출에 입력 약 7,800 토큰이었어요.
• Claude (MCP 사용 시)
  작업 지시와 결과 요약 정도라 적게 듭니다. 다만 스크린샷이나 긴 로그를 직접 읽게 하면 늘어나요.

💡 AI Studio에서 결제를 연결하지 않은 무료 등급 키라면 한도를 넘어도 요청이 거절(429)될 뿐 과금되지 않습니다. 결제가 연결된 프로젝트 키라면 예산 알림을 걸어두는 걸 추천합니다.

 

마무리

Appium은 식별자를 하나하나 지정하고 코드를 짜야 했는데, ARTEMIS는 문장 한 줄로 실기기를 움직일 수 있어서 진입 장벽이 훨씬 낮았습니다. 대신 결과가 LLM 상태에 따라 달라질 수 있고 API 비용이 드는 만큼, 반복 회귀 테스트는 Appium, 탐색형 테스트나 빠른 확인은 ARTEMIS처럼 나눠 쓰면 좋을 것 같아요.

 

ARTEMIS GitHub

https://github.com/google/artemis