한눈에
- Maestro는 mobile.dev(mobile-dev-inc)가 만든 오픈소스(Apache-2.0) 모바일·웹 E2E UI 테스트 프레임워크다. 자세한 소개는 maestro.
- Maestro MCP는 Maestro CLI 안에 들어 있는 mcp 서버다. Claude Code·codex·cursor 같은 코딩 에이전트가 에뮬레이터·시뮬레이터·브라우저를 직접 조작해 자기가 만든 기능을 스스로 확인하고, 반복 실행 가능한 YAML 테스트(Flow)로 남길 수 있게 한다.
- 무료 여부: 로컬에서 쓰는 MCP·Viewer·Studio·CLI는 전부 무료다. 돈이 드는 건 호스팅 기기에서 병렬 실행하는 Maestro Cloud(기기당 월 $250)뿐이다. MCP 도구 중 Cloud용 3개만 Cloud 계정이 필요하다.
무료와 유료의 경계
maestro.dev/pricing 기준(2026-10-04 확인).
| 플랜 | 가격 | 포함 |
|---|---|---|
| Local | 무료·오픈소스 | Maestro MCP, Maestro Viewer, Maestro Studio, Maestro CLI, 로컬 에이전트로 self-healing |
| Cloud | 기기당 월 $250 | 호스팅 Android·iOS·웹 기기, 병렬 실행, 무제한 실행, 리포트, CI·PR/MR 연동. 무료 체험 있음 |
| Enterprise Cloud | 별도 견적 | Cloud 전체 + SSO, 전담 지원, 테스트 케이스 위탁 관리, 보안 심사 |
Cloud 요금은 최대 동시 실행 기기 수로 매긴다. 기기를 늘릴수록 병렬도가 올라간다.
설치
준비물
- Maestro CLI 설치. MCP 서버가 CLI에 들어 있어서 따로 받을 것은 없다. CLI는 Java 기반이라
JAVA_HOME이 잡혀 있어야 한다. - MCP를 지원하는 코딩 에이전트.
에이전트별 등록
핵심은 모두 같다. maestro mcp 명령을 stdio 서버로 등록하면 된다.
| 에이전트 | 방법 |
|---|---|
| Claude Code | claude mcp add maestro -- maestro mcp (범위는 --scope user/project) |
| Codex CLI·Desktop | codex mcp add maestro -- maestro mcp 또는 ~/.codex/config.toml에 추가. Desktop 앱도 같은 설정 파일을 쓴다 |
| Gemini CLI | gemini mcp add maestro maestro mcp |
| GitHub Copilot CLI | 세션에서 /mcp add → Name maestro, Type local, Command maestro mcp |
| Cursor IDE·CLI | 원클릭 설치 버튼, 또는 ~/.cursor/mcp.json(프로젝트는 .cursor/mcp.json) |
| Claude Desktop | claude_desktop_config.json을 직접 수정. 아래 주의 참고 |
나머지 에이전트용 범용 설정:
{
"mcpServers": {
"maestro": { "command": "maestro", "args": ["mcp"] }
}
}PATH나 JAVA_HOME 문제로 실행이 안 되면 바이너리 전체 경로(which maestro로 확인)와 env.JAVA_HOME을 명시한다.
Claude Desktop은 최소 셸로 뜨기 때문에 이 방식이 필수다. Desktop의 Connectors UI는 OAuth 원격 서버만 받으므로, 로컬 stdio 서버인 Maestro는 설정 파일로만 추가할 수 있다.
{
"mcpServers": {
"maestro": {
"command": "/opt/homebrew/bin/maestro",
"args": ["mcp"],
"env": { "JAVA_HOME": "<JAVA_HOME 경로>" }
}
}
}등록한 뒤 에이전트를 재시작하면 끝이다.
MCP 도구 9개
| 도구 | 하는 일 |
|---|---|
list_devices | 로컬에서 쓸 수 있는 기기 목록(Android 에뮬레이터, iOS 시뮬레이터, 웹용 Chromium) |
inspect_screen | 현재 화면의 뷰 계층을 간결한 JSON으로 반환. 요소를 지정하기 전에 호출하고, UI가 바뀔 때마다 다시 부른다 |
take_screenshot | 현재 화면 캡처. 요소가 헷갈릴 때 시각 정보로 구분 |
run | Flow 실행. 인라인 { yaml }(탐색용으로 권장), 파일 { files }, 폴더 { dir, include_tags, exclude_tags } 중 하나만 받는다. 문법 검증도 함께 한다 |
cheat_sheet | Maestro 명령·Flow 문법·모범 사례 요약. 익숙하지 않은 명령을 쓰기 전에 에이전트가 먼저 읽는다 |
list_cloud_devices | Cloud에서 쓸 수 있는 { device_model, device_os } 조합. OS 문자열은 iOS-17-5, android-34처럼 그대로 넘긴다 |
run_on_cloud | Flow(또는 폴더)를 Cloud에 제출하고 upload_id·project_id·대시보드 URL을 바로 반환 |
get_cloud_run_status | Cloud 실행 상태와 Flow별 결과 조회. SUCCESS·ERROR·CANCELED·WARNING 중 하나가 나올 때까지 60초 간격으로 폴링 |
open_maestro_viewer | 실행 중인 Viewer URL 반환 |
Cloud 도구 3개(list_cloud_devices, run_on_cloud, get_cloud_run_status)는 인증이 필요하다. maestro login(권장)을 하거나, 비대화형 환경이면 MAESTRO_CLOUD_API_KEY를 설정한다. 나머지 6개는 계정 없이 로컬에서 동작한다.
실제로 쓰는 흐름
- 에이전트에게 기능 구현을 시킨 뒤 “앱을 띄워서 직접 확인해”라고 요청한다.
- 에이전트가
list_devices로 기기를 고르고inspect_screen으로 화면 구조를 읽는다. 필요하면take_screenshot도 쓴다. run에 인라인 YAML을 넘겨 탭·입력·스크롤을 한 단계씩 실행하며 동작을 검증한다.- 검증된 단계를
.yamlFlow 파일로 저장해 회귀 테스트로 남긴다. 이후run {files}나 CI의 Maestro CLI로 반복 실행한다. - 규모가 커지면
run_on_cloud로 Cloud에서 병렬 실행하고get_cloud_run_status로 결과를 받는다.
Flow 예시(문서 일반 문법 기준):
appId: com.example.app
---
- launchApp
- tapOn: "Login"
- inputText: "user@example.com"
- assertVisible: "Welcome"Maestro Viewer
MCP에 함께 들어 있는 웹 앱이다. iOS 시뮬레이터, Android 에뮬레이터, 실기기 화면을 코딩 에이전트의 내장 브라우저나 일반 브라우저에 띄운다.
MCP가 실행하는 명령을 실시간으로 보여 주고, 화면을 직접 만질 수도 있어서 에이전트 앱을 벗어나지 않고 개발과 확인을 반복할 수 있다.
에이전트에게 “open the maestro viewer”라고 말하면 open_maestro_viewer가 URL을 돌려준다. 문서 데모는 Cursor 내장 브라우저에서 띄운 모습이다.
업데이트
MCP는 CLI에 포함되어 있어서 CLI를 업데이트하면 MCP도 함께 올라간다. 업데이트 뒤 에이전트에서 연결만 다시 맺으면 된다.
- Claude Code:
/mcp→ maestro → Reconnect - Cursor IDE: Settings → Tools & MCPs에서 끄고 다시 켜기
- 그 밖의 에이전트(Claude Desktop, Codex, Copilot CLI, Gemini CLI,
cursor-agent): 재시작
의의
에이전트가 웹 UI를 확인할 때는 브라우저 자동화 MCP를 많이 쓰지만(예: 2026-03-28-dev-browser), 모바일 앱은 에뮬레이터 조작과 접근성 트리 해석이 따로 필요해서 그동안 공백이 컸다(iOS 시뮬레이터 화면을 스트리밍해 에이전트에게 넘기는 serve-sim 같은 시도는 있었다). Maestro MCP는 이미 검증된 블랙박스 테스트 엔진을 그대로 에이전트에 노출한다. 그래서 에이전트의 “확인” 결과가 사람이 읽고 CI에서 다시 돌릴 수 있는 YAML 테스트로 남는다는 점이 차별점이다.