MAS MCP 서버

Claude Code, Cursor, Codex 및 모든 MCP 클라이언트를 위한 안드로이드 MCP 서버

AI 클라이언트에 안드로이드를 보는 눈과 조작하는 손을 주는 도구 25개: 직접 볼 수 있는 스크린샷, OCR과 템플릿 매칭, 탭·스와이프·입력, 매크로 실행, 그리고 한 문장으로 매크로를 만드는 에이전트. Windows나 Mac의 BlueStacks, LDPlayer, MuMu, MEmu 등 adb 호환 에뮬레이터, PC에 연결한 휴대폰, 항상 켜져 있는 클라우드 안드로이드 기기를 원격 엔드포인트 하나로 제어하세요.

MAS 키로 발급한 토큰으로 호스팅 서버를 연결하고, 무료 로컬 커넥터는 stdio 서버로 추가합니다.

claude mcp add --transport http mas https://api.automationmacro.com/mcp --header "Authorization: Bearer $MAS_MCP_TOKEN"
claude mcp add mas-local -- python -m masagent mcp
앱 받기 MAS Agent 알아보기 설정 문서

무엇인가

MAS 안드로이드 MCP 서버가 하는 일

MCP는 AI 클라이언트가 외부 도구를 호출할 때 쓰는 프로토콜입니다. 이 서버는 안드로이드 기기를 그 도구로 바꿉니다. 클라이언트가 스크린샷을 요청하면 직접 볼 수 있는 이미지를 받고, 화면에 무엇이 적혀 있는지 물으면 신뢰도와 박스가 있는 OCR 줄을 받고, 템플릿을 보내면 위치를 돌려받고, 탭·스와이프·입력·키 누르기를 하고, 앱을 열고 닫습니다. 이것은 모든 안드로이드 MCP 서버가 하는 부분이며, 에뮬레이터, 연결한 휴대폰, 클라우드 기기에서 똑같이 동작합니다.

MAS 서버는 기기 서버가 할 수 없는 부분도 합니다. 라이브러리의 매크로를 읽고 실행하고, MAS Agent에게 앱을 탐색해 완성된 Python 매크로를 돌려달라고 요청하고, 에이전트가 학습한 앱 맵과 전체 SDK 레퍼런스를 MCP 리소스로 제공해 클라이언트가 하우스 스타일로 매크로 코드를 쓸 수 있게 합니다. 그래서 기기 계층에서는 안드로이드 자동화용 MCP 서버이고, 그 위 계층인 매크로, 에이전트, 맵에서는 모바일 자동화 MCP 서버입니다. Android Studio 플러그인도, 코딩 어시스턴트도 아닙니다. 기기를 조작합니다.

호스팅 서버

도구 25개 전부, 내 클라우드 기기에서

원격 HTTP 엔드포인트 하나. 클라우드 기기를 임대하고, 조작하고, 서버 측에서 매크로를 실행하고, 에이전트로 새 매크로를 만들고, 앱 맵을 읽습니다. 설치할 것이 없고 PC를 꺼도 됩니다.

로컬 커넥터, 무료

기기·비전 도구 13개, 내 컴퓨터에서

직접 실행하는 stdio 서버입니다. adb가 보는 모든 것을 제어합니다: Windows나 macOS의 BlueStacks, LDPlayer, MuMu, MEmu, 또는 USB 디버깅을 켠 휴대폰. 화면, 입력, OCR, 템플릿 매칭. 계정이 필요 없습니다.

에뮬레이터

안드로이드 에뮬레이터 제어: Windows나 Mac의 BlueStacks, LDPlayer, MuMu, MEmu

로컬 커넥터는 이미 책상 위에 있는 에뮬레이터를 위한 안드로이드 에뮬레이터 MCP 서버입니다. python -m masagent mcp로 시작하고, 인자나 MAS_DEVICE 변수로 기기를 지정하거나, adb가 나열하는 첫 기기를 쓰게 두세요. PATH에 adb만 있으면 되고 외부로 아무것도 보내지 않습니다. 대부분의 사람이 찾는 MCP 안드로이드 에뮬레이터 설정이 이것입니다: 명령 하나, adb, 끝. MAS 앱의 연결 페이지가 단계별로 안내합니다.

  • BlueStacks
  • LDPlayer
  • MuMu
  • MEmu
  • Windows
  • macOS

게임은 접근성 트리 기반 서버가 무너지는 경우입니다: 읽을 트리가 없으니까요. 커넥터는 픽셀로 동작하므로, 모델이 설정 화면을 다루듯 게임 화면도 플레이할 수 있습니다.

클라우드 기기

설치할 것 없는 클라우드 안드로이드 기기

호스팅 서버는 MAS가 대신 운영하는 항상 켜져 있는 기기에 연결됩니다. lease_device가 제어 세션을 열고 모든 기기 도구에 필요한 임대 id를 반환하며, auto_start를 설정하면 중지된 기기를 먼저 부팅합니다. 임대는 호출할 때마다 갱신되고 유휴 10분 후 만료되므로, 잊힌 클라이언트가 기기를 영원히 붙들 수 없습니다. run_macro는 기기에서 서버 측으로 실행되고 author_macro는 MAS Agent를 그 기기에서 작업시킵니다. 둘 다 PC를 꺼 두어도 됩니다.

기기 도구에는 호출당 요금이 없습니다. 계정이 소유한 클라우드 기기에서 동작하며, 기기당 월 $80에 월 크레딧이 포함됩니다. 클라우드 기기 보기.

내 휴대폰

책상 위 휴대폰을 위한 안드로이드 ADB MCP 서버

USB 디버깅을 켜고 휴대폰을 연결하면 로컬 커넥터가 에뮬레이터 옆에 휴대폰을 나열합니다. 모든 화면·입력·비전 도구가 그대로 동작합니다: 모델이 에뮬레이터를 제어하듯 MCP로 안드로이드 휴대폰을 제어할 수 있고, 이미 쓰는 클라이언트에서, 휴대폰에는 아무것도 설치하지 않습니다.

비전

모델이 볼 수 있는 스크린샷, OCR, 템플릿 매칭

  • screenshot은 화면을 이미지 콘텐츠로 반환하므로, 모델이 트리에서 추측하는 대신 직접 봅니다. 로컬 커넥터는 긴 변 기준 1280px로 축소하고 배율을 알려 줍니다.
  • read_text는 화면 전체나 한 영역에 OCR을 실행해 각 줄을 신뢰도와 바운딩 박스와 함께 반환하므로, "Claim이라는 단어를 탭해"가 희망이 아니라 좌표가 됩니다.
  • find_image는 보낸 템플릿을 OpenCV로 매칭하며, 임계값을 직접 정할 수 있고, 점수와 탭할 중심점을 반환합니다.

도구

전체 도구 25개

모든 도구의 이름과 매개변수. "로컬 및 호스팅" 도구는 두 환경 모두에 있고, 나머지는 클라우드 기기가 필요합니다.

Device control

Pick a device and drive it: the same taps, swipes and keys a person would use.

  • list_devices 로컬 및 호스팅
    List the devices your client can reach, with their state. On the hosted server that is your cloud devices; on the local connector, whatever adb can see.
  • lease_device (device_id, auto_start) 호스팅
    Open a control session on one of your cloud devices and get the lease_id every device tool needs. Can boot a stopped device first. Leases expire after ten idle minutes and renew on every call.
  • release_device (lease_id) 호스팅
    End the control session. The device keeps running.
  • tap (x, y) 로컬 및 호스팅
    Tap the screen at device coordinates.
  • swipe (x1, y1, x2, y2, duration_ms) 로컬 및 호스팅
    Swipe between two points for scrolling and drags, with a chosen duration.
  • type_text (text) 로컬 및 호스팅
    Type text into the focused input field.
  • press_key (key) 로컬 및 호스팅
    Press BACK, HOME, ENTER, TAB, DEL or any KEYCODE_ name.
  • open_app (package) 로컬 및 호스팅
    Launch an app by package name.
  • close_app (package) 로컬 및 호스팅
    Force-stop an app by package name.
  • current_app 로컬 및 호스팅
    Report the package in the foreground.
  • screen_size 로컬 및 호스팅
    Return the screen size in pixels, the coordinate space for tap and swipe.
  • wait (ms) 로컬 및 호스팅
    Pause for animations and loading screens, up to ten seconds per call.

Vision

Let the model see the screen and locate things on it without guessing coordinates.

  • screenshot (lease_id) 로컬 및 호스팅
    Capture the screen and return it as an image the model can look at.
  • read_text (region) 로컬 및 호스팅
    OCR the whole screen or one region into text lines, each with a confidence and a bounding box.
  • find_image (template_base64, threshold) 로컬 및 호스팅
    Locate a template image on screen with OpenCV matching and return the match score and tap coordinates.

Macros and runs

Your macro library, readable and runnable from the client. Runs execute server-side on a cloud device.

  • list_macros (page, page_size) 호스팅
    List your saved macros with name, id and type, paged.
  • get_macro_code (macro_id, file) 호스팅
    Read a macro's source: the entry script by default, plus the file listing, or any file you name.
  • run_macro (macro_id, device_id, args) 호스팅
    Start a saved macro on a cloud device, server-side, with optional argument overrides. Returns a run_id.
  • get_run (run_id) 호스팅
    The state of a run, from launching through running to finished or failed, with its message.
  • stop_run (run_id) 호스팅
    Stop a running macro.

Agent authoring

Hand a goal to MAS Agent and get a finished macro back, from any client.

  • author_macro (prompt, device_id, model) 호스팅
    Ask MAS Agent to build a new macro on a cloud device from a plain-language goal. Runs for several minutes and spends AI credits. Returns a session_id.
  • get_agent_session (session_id, after_seq) 호스팅
    Progress of an authoring session: state, summary, the macro id once it exists, and the transcript events after your cursor, including any question the agent asked.
  • answer_agent_session (session_id, qid, answers) 호스팅
    Answer the agent's pending question so it can continue.
  • stop_agent_session (session_id) 호스팅
    Stop a session early. Work done so far is saved.

App maps

What the agent has learned about an app, readable by your client.

  • get_map (package, profile) 호스팅
    The learned menu map of an app: its screens and the proven routes between them.

리소스

클라이언트가 대화를 벗어나지 않고 매크로 코드를 쓸 수 있도록 서버가 게시하는 문서.

  • mas://docs/sdk-reference The full mas SDK reference, so an external agent can write macro code in house style.
  • mas://docs/house-library The house library of helpers the agent and the studio use.

설정

1분 만에 추가하기

호스팅 서버는 OAuth 클라이언트 자격 증명을 사용합니다: 앱의 API 키에서 키를 만들고, 스코프를 고르고, 1시간 동안 유효한 액세스 토큰으로 교환하세요. 그 토큰을 Bearer 헤더로 보냅니다. 로컬 커넥터에는 키가 필요 없습니다. 

curl -s -X POST https://api.automationmacro.com/api/mcp/oauth/token -d grant_type=client_credentials -d client_secret=$MAS_API_KEY

Claude Code

위의 토큰으로 호스팅 서버를, 또는 stdio 명령으로 로컬 커넥터를:

claude mcp add --transport http mas https://api.automationmacro.com/mcp --header "Authorization: Bearer $MAS_MCP_TOKEN"
claude mcp add mas-local -- python -m masagent mcp

Cursor

.cursor/mcp.json에 헤더가 있는 원격 HTTP 항목을:

{
  "mcpServers": {
    "mas": {
      "url": "https://api.automationmacro.com/mcp",
      "headers": { "Authorization": "Bearer <your token>" }
    }
  }
}

Codex CLI

~/.codex/config.toml에, 토큰은 환경 변수로:

[mcp_servers.mas]
url = "https://api.automationmacro.com/mcp"
bearer_token_env_var = "MAS_MCP_TOKEN"

Hermes, OpenCode, Gemini CLI 및 나머지

헤더가 있는 원격 HTTP 서버를 받거나 stdio 명령을 실행하는 모든 클라이언트. Claude Desktop과 claude.ai 커넥터는 대화형 로그인을 기대하므로, 헤더를 추가하는 로컬 브리지를 사용하세요.

{
  "mcpServers": {
    "mas": { "type": "http", "url": "https://api.automationmacro.com/mcp", "headers": { "Authorization": "Bearer <your token>" } },
    "mas-local": { "command": "python", "args": ["-m", "masagent", "mcp"] }
  }
}

확인: 클라이언트에 기기 목록을 요청한 뒤 스크린샷을 요청하세요. 엔드포인트 https://api.automationmacro.com/mcp, 프로토콜 2025-06-18, 디스커버리 문서는 /.well-known 아래에 있습니다.

도구로서의 에이전트

author_macro: AI 탐색에서 완성된 Python 매크로까지

대부분의 안드로이드 MCP 서버는 기기에서 멈춥니다. 이 서버는 에이전트를 건네줍니다. author_macro는 일상 언어의 목표와 클라우드 기기를 받아 MAS Agent 세션을 시작합니다. 세션은 앱을 탐색하고, 필요한 템플릿 이미지와 텍스트 영역을 실제 화면에서 캡처하고, 결정적 Python 매크로를 컴파일하고, 재실행으로 검증합니다. get_agent_session은 커서가 있는 대화 기록과 에이전트의 질문을 반환하고, answer_agent_session이 답합니다. 완성된 매크로는 세션에 id가 담긴 채 라이브러리에 들어가 run_macro로 실행할 수 있으며, 그 이후 모든 실행은 AI 크레딧 0입니다. MAS Agent 보기.

QA

안드로이드 앱 테스트와 QA 워크플로

에뮬레이터나 클라우드 기기의 테스트 빌드에 클라이언트를 연결하고, tap, type_text, press_key로 흐름을 진행하고, read_text나 find_image로 각 화면을 확인하세요. author_macro로 흐름을 한 번 지나가면 예약할 수 있는 반복 가능한 검사가 됩니다. 사용자가 하듯 화면을 통해 앱을 테스트하며, 단위 테스트 프레임워크는 아닙니다.

보안

원격 서버, HTTP 전송, 스코프 키, 그리고 외부로 아무것도 보내지 않는 커넥터

호스팅 서버는 엔드포인트 하나의 HTTPS 기반 무상태 JSON-RPC입니다. 키는 앱에서 만들고, 한 번만 표시되며, 만료일을 둘 수 있고, 클릭 한 번으로 폐기합니다. 키로 발급한 토큰은 1시간 동안 유효합니다. 각 키는 부여한 스코프만 갖습니다:

  • devices:control lease a cloud device, see its screen, tap, type and manage apps
  • macros:run list and read macros, start, check and stop runs
  • macros:author start, follow, answer and stop an agent authoring session
  • maps:read read the learned map of an app

로컬 커넥터는 자체 네트워크 호출을 하지 않습니다: 내 컴퓨터의 adb와 클라이언트하고만 통신합니다.

안드로이드 MCP 서버 FAQ

안드로이드 MCP 서버란 무엇인가요?

MCP(Model Context Protocol)는 Claude Code, Cursor, Codex 같은 AI 클라이언트가 외부 도구를 호출하는 방식입니다. 안드로이드 MCP 서버는 안드로이드 기기를 도구로 노출합니다: 스크린샷 찍기, 화면의 텍스트 읽기, 탭, 스와이프, 입력, 앱 열기. MAS 서버는 도구 25개를 노출하며, 기기 서버만으로는 할 수 없는 것을 더합니다: 저장된 매크로 실행, MAS Agent에게 매크로 제작 요청, 에이전트가 학습한 앱 맵 읽기.

Claude Code를 안드로이드 에뮬레이터에 어떻게 연결하나요?

내 에뮬레이터라면 무료 로컬 커넥터(python -m masagent mcp)를 실행하고 Claude Code에 stdio 서버로 추가하세요. adb가 보는 모든 기기를 제어합니다. 클라우드 기기라면 앱에서 키를 만들고, 토큰으로 교환한 뒤, claude mcp add --transport http와 Bearer 헤더로 호스팅 서버를 추가하세요. 두 스니펫 모두 이 페이지에 있습니다.

BlueStacks, LDPlayer, MuMu, MEmu에서 동작하나요?

예. 로컬 커넥터는 adb devices가 나열하는 모든 것과 통신하며, 여기에는 Windows나 macOS의 BlueStacks, LDPlayer, MuMu, MEmu와 다른 adb 호환 에뮬레이터가 포함됩니다. 특정 에뮬레이터 브랜드에 묶인 것은 없습니다.

Cursor나 Codex가 MCP로 안드로이드 에뮬레이터를 제어할 수 있나요?

예. Cursor는 mcp.json의 Authorization 헤더가 있는 원격 HTTP 항목으로 호스팅 서버를, stdio 명령으로 로컬 커넥터를 받습니다. Codex CLI는 codex mcp add와 환경 변수의 Bearer 토큰으로 호스팅 서버를 받습니다. 어느 쪽이든 같은 도구가 나타납니다.

다른 어떤 MCP 클라이언트가 동작하나요?

Bearer 헤더로 원격 HTTP MCP 서버를 호출하거나 stdio 서버를 실행할 수 있는 모든 클라이언트: Claude Code, Cursor, Codex, Hermes, OpenCode, Gemini CLI 등. Claude Desktop과 claude.ai 사용자 지정 커넥터는 대화형 로그인 흐름을 기대하므로, MAS에서는 헤더를 추가하는 로컬 브리지를 통해 연결합니다.

ADB나 Android Studio를 설치해야 하나요?

로컬 커넥터는 내부적으로 adb를 사용하므로 adb가 PATH에 있어야 합니다. Android Studio는 필요 없습니다. 호스팅 서버는 아무것도 설치할 필요가 없습니다: 클라우드 기기는 서버 측에서 조작되며 클라이언트는 도구만 호출합니다.

모델이 정말 화면을 볼 수 있나요?

예. screenshot은 모델이 직접 보는 이미지로 화면을 반환합니다. read_text는 OCR을 실행해 각 줄을 신뢰도와 바운딩 박스와 함께 반환하고, find_image는 보낸 템플릿을 매칭해 점수와 탭 좌표를 반환합니다. 접근성 트리가 필요 없으며, 그래서 게임에서도 동작합니다.

PC에 연결한 실제 안드로이드 휴대폰을 제어할 수 있나요?

예, 로컬 커넥터를 통해서요. USB 디버깅을 켜고 휴대폰을 연결하면 다른 에뮬레이터처럼 list_devices에 나타납니다. 화면, 입력, 비전 도구가 같은 방식으로 동작합니다.

원격 MCP 서버인가요, 로컬에서 실행되나요?

둘 다입니다. 호스팅 서버는 원격 HTTP 엔드포인트 하나(https://api.automationmacro.com/mcp)로, 클라우드 기기용 도구 25개 전부를 제공합니다. 로컬 커넥터는 내 컴퓨터에서 실행하는 무료 stdio 서버로, 에뮬레이터와 연결한 휴대폰용 기기·비전 도구 13개를 제공합니다. 매크로 실행, 에이전트 제작, 앱 맵은 호스팅 전용입니다.

인증은 어떻게 동작하나요?

OAuth 클라이언트 자격 증명입니다. 앱에서 키를 만들고 스코프를 고르면, 클라이언트가 https://api.automationmacro.com/api/mcp/oauth/token에서 키를 1시간짜리 액세스 토큰으로 교환해 Bearer 토큰으로 보냅니다. 키에는 만료일을 둘 수 있고 언제든 폐기할 수 있습니다. 디스커버리 문서는 /.well-known 아래에 게시됩니다.

author_macro는 무엇을 반환하고, 얼마나 걸리나요?

클라우드 기기에서 MAS Agent 세션을 시작하고 즉시 세션 id를 반환합니다. 에이전트는 몇 분 동안 앱을 탐색합니다. get_agent_session이 커서와 함께 대화 기록을 스트리밍하고 에이전트의 질문을 보여 주며, answer_agent_session으로 답합니다. 끝나면 매크로 id가 세션에 담기고 매크로는 라이브러리에 들어가 run_macro로 실행할 수 있습니다. 제작에는 AI 크레딧이 들고, 완성된 매크로 실행은 0입니다. MAS Agent 보기.

무료인가요? 클라우드 기기는 얼마인가요?

로컬 커넥터는 무료입니다. 호스팅 서버는 MAS 계정의 일부입니다. 기기 도구는 소유한 클라우드 기기에서 동작하며, 기기당 월 $80에 월 크레딧이 포함되고, 기기 도구에는 호출당 요금이 없습니다. 완성된 매크로 실행은 크레딧 0이고, 에이전트 제작은 작업하는 만큼 크레딧을 씁니다. 요금제 보기.

PC를 켜 두지 않고 클라우드 기기에서 24시간 실행할 수 있나요?

예. lease_device가 클라우드 기기에 제어 세션을 열고 중지된 기기를 부팅할 수 있으며, run_macro는 서버 측에서 실행됩니다. PC를 켜 둘 필요가 없고, 임대는 호출할 때마다 갱신되며 유휴 10분 후 만료됩니다. 클라우드 기기 보기.

안드로이드 앱 테스트와 QA에 쓸 수 있나요?

예. 클라이언트를 테스트 빌드에 연결하고, tap, type, press_key로 흐름을 진행하고, read_text나 find_image로 각 화면을 확인하고, author_macro로 한 번 지나간 흐름을 반복 가능한 검사로 바꾸세요. 사용자가 하듯 화면을 통해 앱을 자동화하며, 단위 테스트 프레임워크는 아닙니다.

앱 다운로드 요금제 보기 설정 문서