Android Tester

You can automate Android devices with a dedicated MCP server that exposes tools to spin up Android boxes, capture screenshots, perform AI-driven UI actions, and manage apps. This MCP server lets you control Android environments remotely, making it easier to test, automate tasks, and verify app behavior across devices.

How to use

To use this MCP server, run it as a local (stdio) process and connect to it from your MCP client. You will provide your Gbox API key as an environment variable so the server can authenticate with the Gbox services. Once started, you can invoke the available tools to create Android boxes, take screenshots, perform AI-powered UI actions, and manage applications on your Android devices.

How to install

Prerequisites you need before installation are Node.js and npm. Ensure you have a valid Gbox API key for authentication.

# 1) Install dependencies
npm install

# 2) Set environment variable for the Gbox API key
# Create a .env file in the project root with the following line:
GBOX_API_KEY=your_gbox_api_key_here

# 3) Build the project
npm run build

Configuration to run the MCP server

The server runs as a local process. Use the following configuration to connect your MCP client to this stdio server. Adjust the path to your built index.js according to your project location.

{
  "mcpServers": {
    "gbox_android": {
      "command": "node",
      "args": ["/YOU_PATH_TO_THIS_REPO/android-tester-mcp/dist/index.js"],
      "env": {
        "GBOX_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Additional configuration notes

The server exposes a set of tools to manage Android devices and apps. Make sure your environment variable GBOX_API_KEY remains secret and is not shared in logs or consoles.

Security and best practices

Keep your Gbox API key secure. Run the MCP server in a trusted network environment. Periodically rotate keys and limit access to your MCP client configurations.

Troubleshooting

If the server fails to start, verify that Node.js and npm are installed, the GBOX_API_KEY is set, and the path to dist/index.js is correct after building. Check that the port or IPC channel used by your MCP client is reachable and that there are no conflicting processes using the same resources.

Notes

The server supports creating Android boxes, listing existing boxes, retrieving box details, capturing screenshots, performing AI-driven actions, and handling APKs (install/uninstall) and launching apps. You can manage multiple boxes tied to your Gbox API key, enabling scalable automated testing across devices.

Available tools

create_android_box

Create a new Android box with specified configuration to run tasks on a virtual or physical device.

list_boxes

List all current Android boxes associated with your API key, including status and metadata.

get_box

Get detailed information about a specific Android box, including device type, status, and configuration.

get_screenshot

Capture a screenshot of the current Android device display.

ai_action

Perform UI actions using natural language instructions, enabling AI-assisted automation of interactions.

install_apk

Install an APK file from a local path or URL onto an Android box.

uninstall_apk

Uninstall an app from an Android box by package name.

open_app

Launch an installed application on the Android device.