GBOX Android MCP

GBOX

GBOX 为 AI Agent 提供操作计算机和移动设备的环境。

移动端场景: 你的 Agent 可以使用 GBOX 开发/测试 Android 应用，或在 Android 上运行应用来完成各种任务（移动端自动化）。

桌面端场景: 你的 Agent 可以使用 GBOX 操作浏览器、终端、VSCode 等桌面应用（桌面端自动化）。

MCP: 你还可以将 GBOX MCP 接入任何你喜欢的 Agent，例如 Cursor、Claude Code。这些 Agent 将立即获得操作计算机和移动设备的能力。

安装

系统要求

• MacOS
  • 版本: 10.15 或更高版本
  • Homebrew

注意: 在其他平台上使用 gbox，请查看 npm 包 @gbox.ai/cli 获取安装说明。你也可以登录 GBOX.AI 使用基于 Web 的仪表盘。

安装步骤

快速安装（推荐）

方式 1: 仅安装 GBOX CLI ```bash curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash

这只会安装 GBOX。其他依赖（如 ADB、gbox、Appium）会在需要时自动安装，或者你可以之后使用以下命令安装:
```bash
gbox setup

方式 2: 安装所有依赖（完整设置）

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

这会安装所有内容:

• GBOX CLI
• Node.js 和 npm（如未安装）
• Android Debug Bridge (ADB)
• FRP 客户端 (frpc)
• Appium 服务

非交互模式:

# 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

其他安装方式

通过 Homebrew (macOS):

brew install gbox

通过 npm (Linux/Windows):

npm install -g @gbox.ai/cli

设置依赖

如果你仅安装了 GBOX CLI，你可以随时安装所有命令依赖:

gbox setup

或以交互方式安装它们:

gbox setup -y

更新 GBOX CLI

保持你的 GBOX CLI 为最新版本:

使用安装脚本:

# Interactive update (will prompt if already installed)
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash

# Force update without prompt
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- --update

# Skip update even if newer version available
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- --update=false

使用 Homebrew (macOS):

brew upgrade gbox

使用 npm (Linux/Windows):

npm update -g @gbox.ai/cli

开始使用

# Login to gbox.ai
gbox login

# Connect your Android device (dependencies will be installed automatically if missing)
gbox device-connect

# Export MCP config and merge into Claude Code/Cursor
gbox mcp export --merge-to claude-code
gbox mcp export --merge-to cursor

命令行用法

查看 GBOX CLI 参考 了解详细用法。

SDK 用法

查看 GBOX SDK 参考 了解详细用法。

将 GBOX 用作 MCP 服务（需要登录）

使用 GBOX CLI 将 MCP 服务配置到你的 Claude Code/Cursor:

# Export MCP config for Cursor
gbox mcp export --merge-to cursor

# Export MCP config for Claude Code
gbox mcp export --merge-to claude-code --scope project

或将以下内容复制粘贴到你的 Claude Code/Cursor MCP 配置中:

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

注意:

• 目前，GBOX MCP 只能控制 Android 环境。
• 如果你需要 Cursor/Claude Code 控制你的本地 Android 设备，请查看 注册本地设备

Android MCP 用例

用例	演示
Claude Code 开发/测试 Android 应用
Claude Code 在电商应用中比价

环境

目前，GBOX 支持以下环境:

• Android
• Linux 桌面/浏览器

Android 环境

共有三种类型的 Android 环境，你可以根据需求选择：

1. 云虚拟设备：

登录 GBOX.AI 获取云虚拟设备。最适合测试和开发。

2. 云真机设备：

登录 GBOX.AI 获取云真机设备。云真机设备是一台真实的 Android 手机，可用于生产场景。

3. 本地真机设备：

使用你自己的真机设备注册本地设备。你的本地设备可以是任何已启用开发者模式的 Android 设备。最适合生产场景和个人使用。

Linux 桌面/浏览器环境

登录 GBOX.AI 获取 Linux 桌面/浏览器环境。最适合测试和开发。

开发 gbox

前置条件

• Go 1.21 或更高版本
• Make
• pnpm（通过 corepack）
• Node.js 16.13 或更高版本

构建

# Build for current platform
make build

# Build for all platforms
make build-all

# Create distribution package
make dist

运行服务

# MCP Server
cd packages/mcp-server && pnpm dev

# MCP Inspector
cd packages/mcp-server && pnpm inspect

贡献

我们欢迎贡献！请随时提交 Pull Request。对于重大更改，请先开一个 issue 讨论你想更改的内容。

1. Fork 仓库
2. 创建你的功能分支（git checkout -b username/feature-name）
3. 提交你的更改（git commit -m 'Add some feature'）
4. 推送到分支（git push origin username/feature-name）
5. 打开一个 Pull Request

关于本地开发和调试需要了解的事项

许可证

本项目采用 Apache License 2.0 许可证 - 详情请参阅 LICENSE 文件。