home / mcp / gbox mcp server

GBOX MCP Server

Provides MCP-enabled access to GBOX Android and Linux environments for automated control by MCP clients.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "babelcloud-gru-sandbox": {
      "command": "npx",
      "args": [
        "-y",
        "@gbox.ai/mcp-server@latest"
      ]
    }
  }
}

GBOX MCP lets you expose Android environments through MCP clients so you can operate devices from tools like Cursor or Claude Code. You export a server configuration that connects your MCP client to GBOX, enabling automated control of Android environments for development, testing, and automation tasks.

How to use

You use GBOX as an MCP server by exporting MCP configurations with the GBOX CLI and then loading those configurations into your MCP client (Cursor or Claude Code). Once connected, your client can remotely start and manage Android environments provided by GBOX, enabling automated app testing, mobile automation, and desktop automation workflows.

How to install

Prerequisites: You need Node.js and npm installed on your system. You also have options to install using macOS Homebrew or via npm for Linux/Windows.

# Quick check for Node and npm
node -v
npm -v

Choose one of the following installation flows. Each flow installs the GBOX CLI and pulls in required dependencies as needed.

# Option 1: Install GBOX CLI only
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash

gbox setup

# Option 2: Install with all dependencies in one go
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- --with-deps

Non-Interactive Mode (skip prompts):

# CLI only
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- -y

# With all dependencies
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- -y --with-deps

Alternative methods (macOS and Linux/Windows):

# macOS via Homebrew
brew install gbox

# Linux/Windows via npm
npm install -g @gbox.ai/cli

Additional setup and usage notes

After installing the CLI, you can set up dependencies, log in, and export MCP configs for your clients.

Common commands you will use include logging in, connecting Android devices, and exporting MCP configs for your MCP clients.

MCP server connections example

You can export MCP configurations for your MCP clients and load them into the corresponding client. The following example shows how to export a server config targeting Android environments via a local MCP command. You can export separate configs for Cursor and Claude Code.

{
  "mcpServers": {
    "gbox-android": {
      "command": "npx",
      "args": [
        "-y",
        "@gbox.ai/mcp-server@latest"
      ]
    }
  }
}

Android MCP Use Cases

Use cases include Claude Code developing/testing Android apps and Claude Code comparing prices on Android apps. These demonstrations show how you can leverage GBOX to automate mobile tasks within Android environments.

Environments

GBOX currently supports Android environments and Linux desktop/browser environments. Android environments can be cloud virtual devices, cloud physical devices, or local physical devices with Developer Mode enabled. Linux desktop/browser environments provide a Linux desktop for testing and development.

Develop gbox

GBOX is built with Go, Make, pnpm, and Node.js. Build and run locally by following the build and run steps to create MCP server and inspector services for development and debugging.

Notes on MCP configuration and usage

Export MCP config for Cursor using: gbox mcp export --merge-to cursor
Export MCP config for Claude Code using: gbox mcp export --merge-to claude-code --scope project

Available tools

login

Authenticate with the GBOX service to access MCP features and cloud environments.

device_connect

Connect your Android device to the GBOX environment so it can be controlled by MCP clients.

export_mcp

Export MCP configuration for a specified MCP client and merge it into the target client setup.

setup_dependencies

Install and configure required command dependencies for blue-green environments and MCP servers.

mcp_server

Run the MCP server component to listen for MCP client connections and serve environment operations.