# 파이썬 안드로이드 자동화 시작하기: 첫 매크로 실행

> Macro Automation Studio에서 파이썬 안드로이드 자동화를 시작합니다: 기기를 연결한 뒤 마켓플레이스 봇 실행, MAS Agent 요청, 첫 매크로 작성까지 안내합니다.

Source: https://automationmacro.com/ko/docs/getting-started (시작하기, updated 2026-09-05)

파이썬 안드로이드 자동화 도구인 Macro Automation Studio(MAS)는 화면을 통해 Android 앱을 조작합니다. 기기 화면을 보고, 필요한 것을 찾고, 탭합니다. 이 페이지는 파이썬 안드로이드 자동화를 처음 시작하는 분을 위해, 설치 직후부터 Android 에뮬레이터, 클라우드 기기 또는 휴대폰에서 첫 파이썬 매크로를 실행하기까지의 과정을 다룹니다. Windows와 Mac 모두 해당됩니다.

## 시작하기 전에

- MAS가 설치되어 있고 로그인한 상태여야 합니다. [MAS 설치](/docs/install)를 참고하세요.
- 자동화할 대상이 있어야 합니다: 이 컴퓨터의 Android 에뮬레이터, 클라우드 기기, 또는 본인의 휴대폰. [기기](/docs/devices)를 참고하세요.
- 계정에 활성 구독 또는 무료 체험이 있어야 합니다. 로그인과 **Subscription**을 제외한 앱의 모든 페이지에 필요합니다. 없으면 MAS는 **Subscription**을 열고 거기서 멈춥니다. 요금제는 [가격 페이지](/pricing)에 있습니다.

> [!NOTE]
> Python SDK는 이미 설치되어 있습니다. MAS는 `mas` 패키지가 포함된 자체 Python 3.13 환경을 함께 제공하므로, 별도 설정 없이 Code Editor에서 `import mas`가 바로 동작합니다.

## 안드로이드 에뮬레이터 매크로 설정: 기기 선택

실행은 기기 하나를 대상으로 합니다. 상황에 맞는 종류를 고르세요:

| 기기 | 실행 위치 | 적합한 용도 |
|---|---|---|
| 에뮬레이터 (BlueStacks, LDPlayer, MuMu Player, MEmu) | 이 컴퓨터, adb 경유 | 첫 시도와 로컬 테스트 |
| 클라우드 기기 | MAS 클라우드, WebRTC로 앱에 스트리밍 | 컴퓨터를 꺼도 계속되는 실행 |
| 본인 휴대폰 | 이 컴퓨터, adb 경유 (고급) | 실제 하드웨어에서만 제대로 동작하는 앱 |

에뮬레이터를 추가하려면:

1. 에뮬레이터를 시작하고 설정에서 ADB를 켭니다. 어디에 설정이 있는지는 각 에뮬레이터 가이드에 나와 있습니다.
2. MAS에서 **Device Groups**를 열고 **Create New Group**을 클릭합니다. 유형은 **Local**로 둡니다.
3. 그룹을 열고 **Add Device**를 클릭합니다.
4. **Device Name**을 입력하고 **Port** 목록에서 에뮬레이터의 포트를 고릅니다. 목록이 비어 있으면 **Refresh**를 클릭합니다.
5. **Add Device**를 클릭합니다.

클라우드 기기는 **Cloud Devices** 페이지에서 **Create**로 만들며, 로컬 기기 옆에 실행 대상으로 나타납니다. 휴대폰 연결 방법은 [기기](/docs/devices) 페이지에 있습니다.

## 매크로를 얻는 세 가지 방법

### 마켓플레이스 봇 실행

1. **Marketplace**를 열고 앱이나 게임을 검색합니다.
2. 목록을 열고 **Download**를 클릭합니다. 봇이 **Macros**에 "Downloaded from Marketplace" 태그와 함께 나타납니다.
3. **Device Groups**에서 그룹을 열고, 기기의 **Macro** 선택기에서 봇을 고른 뒤 **Start**를 클릭합니다.
4. 기기 카드의 **Logs** 탭을 확인합니다. 끝나면 **Stop**을 클릭합니다.

스크린샷이 포함된 전체 과정은 [마켓플레이스에서 매크로 실행하기](/docs/run-macro-from-marketplace)에 있습니다. 직접 만든 봇을 게시하는 방법은 [Marketplace](/docs/marketplace) 페이지에서 다룹니다.

### MAS Agent에 요청

1. **Agent**를 열고 **Device**에서 기기를 고릅니다.
2. 작업을 일상 언어로 설명하고 **Author**를 클릭합니다.
3. "The agent needs your input" 카드가 나타나면 답합니다. 에이전트는 추측하지 않고 멈춰서 질문합니다.
4. 매크로가 검증 실행 3회를 통과하면 **Add to My Macros**를 클릭합니다.

결과물은 Code Editor에서 열 수 있는 일반 파이썬 프로젝트입니다. 작성에는 AI 크레딧이 들지만, 완성된 매크로 실행에는 크레딧이 들지 않습니다. 자세한 내용은 [MAS Agent](/docs/agent) 페이지를 참고하세요.

### 파이썬으로 안드로이드 에뮬레이터 자동화 작성

1. **Macros**를 열고 **Create New Project**를 클릭합니다.
2. **Code-Based**를 선택하고 **Target Device**를 mobile로 설정한 뒤 프로젝트 이름을 입력하고 **Create Project**를 클릭합니다.
3. 프로젝트를 엽니다. Code Editor에 `src/app.py`가 표시됩니다. 아래 스크립트를 붙여 넣습니다.
4. 기기를 고르고 **Run**(<kbd>F5</kbd>)을 클릭합니다. **Stop**은 <kbd>Shift</kbd>+<kbd>F5</kbd>, **Save**는 <kbd>Ctrl</kbd>+<kbd>S</kbd>입니다.

[SDK 개요](/docs/sdk)에서 네임스페이스를 설명하고, [API 레퍼런스](/docs/api-reference)에 모든 함수가 정리되어 있습니다.

## 첫 스크립트

이 스크립트는 기기 정보를 읽고, 스크린샷을 찍고, 화면 전체에 OCR을 실행합니다. 기기에서 바뀌는 것은 없습니다.

```python
import mas

device = mas.get_device_info()
print(f"Connected to: {device.name}")

screen = mas.get_screen_size()
print(f"Screen: {screen.width}x{screen.height}")

shot = mas.take_screenshot()
print(f"Screenshot: {shot.width}x{shot.height}")

result = mas.read_text()
print(f"Screen text: {result.text[:100]}")

mas.log("First script finished")
```

`mas.log`는 실행 콘솔에 레벨이 붙은 줄을 씁니다. 일반 `print`도 동작합니다.

## 자주 쓰는 패턴

### 이미지를 찾아 탭하기

Asset Lab에서 버튼을 잘라 Image Library에 ID와 함께 저장한 뒤, `mas.images`로 선언합니다. `find_object_retry`는 2초 간격으로 최대 세 번 찾고, 아무것도 맞지 않으면 `None`을 반환합니다.

```python
import mas

images = mas.images({"play_button": 42})

match = mas.find_object_retry(images.play_button, total_tries=3, time_sleep=2.0)
if match:
    mas.click(match.x, match.y, delay_ms=1000)
else:
    mas.log("Play button not found", level="warning")
```

`find_object`는 기본적으로 임계값 0.8로 매칭합니다. `click`은 앱이 반응할 수 있도록 탭 후 1000 ms를 기다립니다. 빠른 반복문에서는 `delay_ms`를 낮추세요.

### 영역에서 텍스트 읽기

```python
import mas
from mas import Region

score = mas.read_text(region=Region(x1=800, y1=10, x2=1050, y2=60), psm=7)
if score.text.strip().isdigit():
    print(f"Current score: {int(score.text)}")
```

`psm=7`은 영역을 한 줄로 취급하므로 카운터에 알맞습니다. 좌표를 복사하기 전에 Asset Lab에서 영역을 그리고 실시간으로 테스트하세요.

### 오류 처리

```python
import mas

try:
    match = mas.find_object_retry(42)
    if match:
        mas.click(match.x, match.y)
except mas.DeviceNotConnectedError:
    mas.log("No device connected", level="error")
except mas.ImageNotFoundError:
    mas.log("Image ID is not in your library", level="error")
except mas.TimeoutError:
    mas.log("The device did not answer in time", level="error")
except mas.RPCError as e:
    mas.log(f"RPC error: {e}", level="error")
```

## 문제 해결

### Could not discover RPC port

스크립트가 MAS 밖에서 시작되었거나 앱이 실행 중이 아닙니다. Code Editor나 기기 카드에서 스크립트를 실행하세요. 앱이 연결 정보를 넘겨주며 실행합니다.

### 클릭한 페이지 대신 Subscription이 열림

이용 권한이 없거나 만료되었습니다. 체험을 시작하거나 요금제를 고른 뒤 돌아오세요. [결제](/docs/billing)를 참고하세요.

### 기기를 찾을 수 없거나 Connecting에서 멈춤

에뮬레이터의 ADB가 꺼져 있거나, 에뮬레이터가 아직 부팅 중이거나, 다른 포트를 사용하고 있습니다. [ADB 문제 해결](/docs/adb-troubleshooting)을 참고하세요.