MAS MCP server

Android MCP server for Claude Code, Cursor, Codex and any MCP client

25 tools that give your AI client eyes and hands on Android: screenshots it can look at, OCR and template matching, taps, swipes and typing, macro runs, and an agent that builds a macro from a sentence. Drive BlueStacks, LDPlayer, MuMu, MEmu or any adb-compatible emulator on Windows or Mac, a phone plugged into your PC, or always-on cloud Android devices from one remote endpoint.

Hosted server with a token from your MAS key, then the free local connector as a stdio server.

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
Get the app Meet MAS Agent Setup docs

What it is

What the MAS Android MCP server does

MCP is the protocol AI clients use to call outside tools. This server turns an Android device into those tools. Your client asks for a screenshot and gets an image it can look at; asks what the screen says and gets OCR lines with confidence and boxes; sends a template and gets back where it is; taps, swipes, types and presses keys; opens and closes apps. That is the part every Android MCP server does, and it works the same on an emulator, a plugged-in phone or a cloud device.

The MAS server also does the part a device server cannot. It reads and runs the macros in your library, it asks MAS Agent to explore an app and hand back a finished Python macro, and it exposes the map the agent learned of that app, plus the full SDK reference as an MCP resource so your client can write macro code in house style. That makes it an MCP server for Android automation at the device layer, and a mobile automation MCP server for the layers above it: macros, the agent, the maps. It is not an Android Studio plugin and not a coding assistant. It drives the device.

Hosted server

All 25 tools, on your cloud devices

One remote HTTP endpoint. Lease a cloud device, drive it, run macros server-side, author new ones with the agent, read app maps. Nothing to install, and your PC can be off.

Local connector, free

13 device and vision tools, on your machine

A stdio server you run yourself. It drives anything adb can see: BlueStacks, LDPlayer, MuMu, MEmu on Windows or macOS, or a phone with USB debugging. Screen, input, OCR and template matching. No account needed.

Emulators

Control Android emulators: BlueStacks, LDPlayer, MuMu, MEmu on Windows or Mac

The local connector is an Android emulator MCP server for the emulator already on your desk. Start it with python -m masagent mcp, point it at a device with an argument or the MAS_DEVICE variable, or let it take the first device adb lists. It needs adb on your PATH and nothing else, and it never calls home. This is the MCP Android emulator setup most people are looking for: one command, adb, done. The MAS app's Connect page walks you through it.

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

Games are the case that breaks accessibility-tree servers: there is no tree to read. The connector works from pixels, so a model can play through a game screen the way it plays through a settings screen.

Cloud devices

Cloud Android devices, nothing to install

The hosted server reaches the always-on devices MAS runs for you. lease_device opens a control session and returns the lease id every device tool needs; set auto_start and it boots a stopped device first. A lease renews on every call and expires after 10 idle minutes, so a forgotten client cannot hold a device forever. run_macro executes on the device server-side and author_macro puts MAS Agent to work on it, both with your PC off.

Device tools carry no per-call charge; they work on the cloud devices your account owns, $80/mo each with the monthly credit allowance. See cloud devices.

Your own phone

An Android ADB MCP server for the phone on your desk

Enable USB debugging, plug the phone in, and the local connector lists it next to your emulators. Every screen, input and vision tool works on it: a model can control an Android phone through MCP the same way it controls an emulator, from the client you already use, with nothing installed on the phone.

Vision

Screenshots the model can see, OCR and template matching

  • screenshot returns the screen as image content, so the model looks at it directly instead of guessing from a tree. The local connector scales it to 1280 px on the long edge and reports the scale factor.
  • read_text runs OCR on the screen or one region and returns each line with a confidence and a bounding box, so "tap the word Claim" is a coordinate, not a hope.
  • find_image matches a template you send with OpenCV, with a threshold you control, and returns the score and the centre to tap.

Tools

All 25 tools

Every tool by name, with its parameters. "Local and hosted" tools exist on both surfaces; the rest need a cloud device.

Device control

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

  • list_devices local and hosted
    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) hosted
    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) hosted
    End the control session. The device keeps running.
  • tap (x, y) local and hosted
    Tap the screen at device coordinates.
  • swipe (x1, y1, x2, y2, duration_ms) local and hosted
    Swipe between two points for scrolling and drags, with a chosen duration.
  • type_text (text) local and hosted
    Type text into the focused input field.
  • press_key (key) local and hosted
    Press BACK, HOME, ENTER, TAB, DEL or any KEYCODE_ name.
  • open_app (package) local and hosted
    Launch an app by package name.
  • close_app (package) local and hosted
    Force-stop an app by package name.
  • current_app local and hosted
    Report the package in the foreground.
  • screen_size local and hosted
    Return the screen size in pixels, the coordinate space for tap and swipe.
  • wait (ms) local and hosted
    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) local and hosted
    Capture the screen and return it as an image the model can look at.
  • read_text (region) local and hosted
    OCR the whole screen or one region into text lines, each with a confidence and a bounding box.
  • find_image (template_base64, threshold) local and hosted
    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) hosted
    List your saved macros with name, id and type, paged.
  • get_macro_code (macro_id, file) hosted
    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) hosted
    Start a saved macro on a cloud device, server-side, with optional argument overrides. Returns a run_id.
  • get_run (run_id) hosted
    The state of a run, from launching through running to finished or failed, with its message.
  • stop_run (run_id) hosted
    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) hosted
    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) hosted
    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) hosted
    Answer the agent's pending question so it can continue.
  • stop_agent_session (session_id) hosted
    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) hosted
    The learned menu map of an app: its screens and the proven routes between them.

Resources

Documents the server publishes so a client can write macro code without leaving the conversation.

  • 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.

Setup

Add it in a minute

The hosted server uses OAuth client credentials: create a key in the app under API keys, pick its scopes, and exchange it for an access token that lives 1 hour. Send that token as a bearer header. The local connector needs no key. 

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

Hosted server with the token from above, or the local connector as a stdio command:

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

In .cursor/mcp.json, a remote HTTP entry with the header:

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

Codex CLI

In ~/.codex/config.toml, with the token in an environment variable:

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

Hermes, OpenCode, Gemini CLI and the rest

Any client that takes a remote HTTP server with a header, or launches a stdio command. Claude Desktop and claude.ai connectors expect an interactive sign-in, so use a local bridge that adds the header.

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

Verify it: ask your client to list devices, then for a screenshot. Endpoint https://api.automationmacro.com/mcp, protocol 2025-06-18, discovery documents under /.well-known.

The agent, as a tool

author_macro: from an AI exploration to a finished Python macro

Most Android MCP servers stop at the device. This one hands you the agent. author_macro takes a plain-language goal and a cloud device and starts a MAS Agent session that explores the app, captures the template images and text regions it needs from the live screen, compiles a deterministic Python macro and validates it by replay. get_agent_session returns the transcript with a cursor and any question the agent asked; answer_agent_session answers it. The finished macro lands in your library with its id in the session, ready for run_macro, and every run after that costs zero AI credits. See MAS Agent.

QA

Android app testing and QA workflows

Point a client at a test build on an emulator or a cloud device, drive the flow with tap, type_text and press_key, and assert each screen with read_text or find_image. Walk the flow once with author_macro and it becomes a repeatable check you can schedule. It tests the app through the screen the way a user does; it is not a unit test framework.

Security

Remote server, HTTP transport, scoped keys, and a connector that never calls home

The hosted server is stateless JSON-RPC over HTTPS on one endpoint. Keys are created in the app, shown once, can carry an expiry date and are revoked with a click; tokens minted from them live 1 hour. Each key carries only the scopes you grant:

  • 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

The local connector makes no network calls of its own: it talks to adb on your machine and to your client, nothing else.

Android MCP server FAQ

What is an Android MCP server?

MCP (Model Context Protocol) is how AI clients such as Claude Code, Cursor and Codex call outside tools. An Android MCP server exposes an Android device as tools: take a screenshot, read the text on it, tap, swipe, type, open an app. The MAS server exposes 25 tools, and adds what a device server alone cannot: run a saved macro, ask MAS Agent to build one, and read the map it learned of an app.

How do I connect Claude Code to an Android emulator?

For your own emulator, run the free local connector (python -m masagent mcp) and add it to Claude Code as a stdio server; it drives any device adb can see. For a cloud device, create a key in the app, exchange it for a token, and add the hosted server with claude mcp add --transport http and a bearer header. Both snippets are on this page.

Does it work with BlueStacks, LDPlayer, MuMu, MEmu?

Yes. The local connector talks to whatever adb devices lists, which covers BlueStacks, LDPlayer, MuMu, MEmu and the other adb-compatible emulators, on Windows or macOS. Nothing in it is tied to one emulator brand.

Can Cursor or Codex control an Android emulator through MCP?

Yes. Cursor takes the hosted server as a remote HTTP entry in mcp.json with an Authorization header, and the local connector as a stdio command. Codex CLI takes the hosted server with codex mcp add and a bearer token from an environment variable. The same tools appear in each.

Which other MCP clients work?

Any client that can call a remote HTTP MCP server with a bearer header, or launch a stdio server: Claude Code, Cursor, Codex, Hermes, OpenCode, Gemini CLI and others. Claude Desktop and claude.ai custom connectors expect an interactive sign-in flow, so with MAS they connect through a local bridge that adds the header.

Do I need ADB or Android Studio installed?

The local connector uses adb under the hood, so adb has to be on your PATH; Android Studio is not needed. The hosted server needs nothing installed at all: cloud devices are driven server-side and your client only calls tools.

Can the model actually see the screen?

Yes. screenshot returns the screen as an image the model looks at directly. read_text runs OCR and returns each line with a confidence and a bounding box, and find_image matches a template you send and returns the score and the tap coordinates. No accessibility tree is required, which is why it works on games.

Can I control a physical Android phone plugged into my PC?

Yes, through the local connector. Enable USB debugging, plug the phone in, and it shows up in list_devices like any emulator. The screen, input and vision tools work the same way.

Is it a remote MCP server or does it run locally?

Both. The hosted server is one remote HTTP endpoint, https://api.automationmacro.com/mcp, with all 25 tools for your cloud devices. The local connector is a free stdio server you run on your own machine with 13 device and vision tools for emulators and plugged-in phones. Macro runs, agent authoring and app maps are hosted-only.

How does authentication work?

OAuth client credentials. You create a key in the app and choose its scopes; your client exchanges the key for a one-hour access token at https://api.automationmacro.com/api/mcp/oauth/token and sends it as a bearer token. Keys can carry an expiry date and can be revoked at any time. Discovery documents are published under /.well-known.

What does author_macro return, and how long does it take?

It starts a MAS Agent session on a cloud device and returns a session id at once. The agent explores the app for several minutes; get_agent_session streams its transcript with a cursor and surfaces any question it asks, which you answer with answer_agent_session. When it finishes, the macro id is in the session and the macro is in your library, ready for run_macro. Authoring spends AI credits; running the finished macro costs zero. See MAS Agent.

Is it free? What does a cloud device cost?

The local connector is free. The hosted server is part of your MAS account; its device tools work on the cloud devices you own, $80/mo each with the monthly credit allowance, and there is no per-call charge on device tools. Running a finished macro costs zero credits; agent authoring spends credits as it works. See pricing.

Can it run 24/7 on a cloud device without my PC on?

Yes. lease_device opens a control session on a cloud device and can boot a stopped one; run_macro executes server-side. Your PC does not need to stay on, and a lease renews on every call and expires after 10 idle minutes. See cloud devices.

Can I use it for Android app testing and QA?

Yes. Point a client at a test build, drive the flow with tap, type and press_key, assert each screen with read_text or find_image, and let author_macro turn a flow you walk once into a repeatable check. It automates the app through the screen the way a user does; it is not a unit test framework.

Download the app See pricing Setup docs