Quash — Mobile App Automation

Quash MCP

Quash MCP 服务让 AI Agent（Claude Code、Claude Desktop、Cursor，……）能够在已连接的设备上驱动真实的移动应用自动化：运行自然语言测试任务，根据提示词／文档／代码库生成测试用例，管理应用和构建，并获取流式运行结果和报告——这一切都由 Quash（mahoraga）自动化引擎提供支持。

本指南介绍如何在 macOS 或 Windows 上安装、将其接入 Agent、生成 API 令牌、准备设备，以及使用每个工具。

---

平台支持

平台	Android	iOS（模拟器 + 真机）	安装程序
macOS（Apple Silicon）	✅	✅	install.sh（curl … | sh）
Windows（x64）	✅	❌ （Apple 工具链仅适用于 macOS）	install.ps1（irm … | iex）

iOS 自动化需要 Xcode／WebDriverAgent／devicectl／iproxy，这些仅在 macOS 上提供，因此 iOS 工具（setup_simulator、setup_device）仅出现在 macOS 版本中。Windows 仅支持 Android。Linux x86_64 可从源代码构建，但不提供发布版二进制文件。

---

1. 前置条件

• macOS 13+（Apple Silicon） 或 Windows 10/11（x64）。
• Android 自动化需要将 adb（Android platform-tools）添加到 PATH。在 Windows 上，安装程序还会检测 %LOCALAPPDATA%\Android\Sdk。
• **一台设备：**Android 设备／模拟器（已开启 USB 调试），或者在 macOS 上使用 iOS 模拟器或实体 iPhone（已开启开发者模式、已信任并通过 USB 连接）。
• 用于身份验证的 Quash 账户（在第 3 步获取令牌，或在第 5 步通过浏览器登录）。
• 在 macOS 上进行 iOS 自动化：需安装 Xcode（用于构建 WebDriverAgent）。

安装程序还会下载自动化引擎、捆绑的测试生成组件，以及安装到 Android 设备上的 Portal APK。

---

2. 安装

只需运行一条命令，即可安装所有内容，并在找到的每个受支持的 Agent 配置中自动注册 MCP 服务（Claude Code、Claude Desktop、Cursor）。选择你的平台：

macOS

curl -fsSL https://raw.githubusercontent.com/Oscorp-HQ/quash-mcp-releases/main/install.sh | sh

Windows（PowerShell）

irm https://raw.githubusercontent.com/Oscorp-HQ/quash-mcp-releases/main/install.ps1 | iex

这会将最新版本安装到 ~/.quash（macOS）／%USERPROFILE%\.quash（Windows），并自动连接到 Quash 生产环境——无需配置后端 URL。

**Cursor 用户：**运行上述安装程序（引擎所需）后，你可以一键将 MCP 服务添加到 Cursor：

（安装程序已自动注册 Cursor，因此只有在你跳过此步骤或移除了对应条目时，才需要这样做。）

选项（环境变量）

**macOS 注意事项：**环境变量必须放在管道命令的 sh 前，而不是放在 curl 前——curl 前的变量前缀会被忽略。在 Windows 上，请在运行 irm 前设置 $env:…。

macOS — 配置令牌／固定版本：

# Token at install time (recommended — see step 3):
curl -fsSL https://raw.githubusercontent.com/Oscorp-HQ/quash-mcp-releases/main/install.sh | QUASH_API_TOKEN=qsh_xxxxxxxx sh

# Pin a specific version:
curl -fsSL https://raw.githubusercontent.com/Oscorp-HQ/quash-mcp-releases/main/install.sh | QUASH_VERSION=v1.1.0 sh

Windows — 同样通过 $env: 设置：

$env:QUASH_API_TOKEN = "qsh_xxxxxxxx"
irm https://raw.githubusercontent.com/Oscorp-HQ/quash-mcp-releases/main/install.ps1 | iex

环境变量	默认值	用途
QUASH_API_TOKEN	（未设置）	API 令牌；若已设置，MCP 会在启动时自动登录
QUASH_VERSION	latest	要安装的发行版标签
QUASH_BACKEND_URL	production	覆盖后端（staging/local）
QUASH_FORCE	0	设为 1 时，即使版本匹配也会强制完整重新安装

可以放心地重新运行安装程序：它会刷新配置；设置 QUASH_FORCE=1 时，还会重新安装二进制文件。重新连接 Agent 不会更新服务——只有重新运行安装程序才会更新。

---

3. 从 Quash 应用生成 API 令牌

该令牌可让 MCP 无需浏览器即可进行身份验证。（不想管理令牌？跳到第 5 步，改用 Google 登录。）

1. 打开 Quash 桌面应用并登录。
2. 前往 Settings → Integrations。
3. 点击 Generate token（或重新生成，以替换现有令牌）。
4. 复制令牌——它以 qsh_ 开头。令牌只会显示一次，请妥善保存。

生成新令牌会使之前的令牌失效，因此请在所有使用它的地方更新令牌。令牌仅对你当前登录的组织有效，并且只存储在 Agent 的 MCP 配置 env 区块中——绝不会通过聊天传递。

---

4. 将其添加到 Agent

安装程序会自动注册 quash 服务，因此通常无需进行任何操作。如需验证或手动添加，配置项如下——请使用适用于你平台的路径：

macOS

{
  "mcpServers": {
    "quash": {
      "type": "stdio",
      "command": "/Users/<you>/.quash/bin/quash-mcp",
      "env": {
        "QUASH_SIDECAR_CMD": "/Users/<you>/.quash/sidecar/quash-sidecar/quash-sidecar",
        "QUASH_TEST_GEN_AGENT_CMD": "/Users/<you>/.quash/test-gen-venv/bin/python -m test_gen_agent",
        "QUASH_API_TOKEN": "qsh_xxxxxxxx"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "quash": {
      "type": "stdio",
      "command": "C:\\Users\\<you>\\.quash\\bin\\quash-mcp\\quash-mcp.exe",
      "env": {
        "QUASH_SIDECAR_CMD": "C:\\Users\\<you>\\.quash\\sidecar\\quash-sidecar\\quash-sidecar.exe",
        "QUASH_API_TOKEN": "qsh_xxxxxxxx",
        "ANDROID_HOME": "C:\\Users\\<you>\\AppData\\Local\\Android\\Sdk"
      }
    }
  }
}

配置文件位置：Claude Code → ~/.claude.json（macOS）/ %USERPROFILE%\.claude.json（Windows）；Claude Desktop → ~/Library/Application Support/Claude/claude_desktop_config.json / %APPDATA%\Claude\claude_desktop_config.json；Cursor → ~/.cursor/mcp.json / %USERPROFILE%\.cursor\mcp.json。

编辑配置后，重启 Agent（或在 Claude Code 中选择 /mcp → reconnect）。

JetBrains IDE（IntelliJ IDEA、PyCharm）

JetBrains AI Assistant 支持通过 stdio 使用 MCP。运行安装程序（第 2 步）后：

1. 打开 Settings → Tools → AI Assistant → Model Context Protocol (MCP)。

2. **最简单的方法：**点击 Import from Claude——由于安装程序已在 Claude Desktop 中注册 Quash，系统会自动导入 quash 服务。

3. **或者手动添加：**点击 Add，然后粘贴此 JSON（JetBrains 不会展开环境变量，因此请使用绝对路径——将 <you> 替换为你的用户名）：

   macOS

   {
     "mcpServers": {
       "quash": {
         "command": "/Users/<you>/.quash/bin/quash-mcp",
         "env": {
           "QUASH_SIDECAR_CMD": "/Users/<you>/.quash/sidecar/quash-sidecar/quash-sidecar",
           "QUASH_TEST_GEN_AGENT_CMD": "/Users/<you>/.quash/test-gen-venv/bin/python -m test_gen_agent"
         }
       }
     }
   }
   

   Windows

   {
     "mcpServers": {
       "quash": {
         "command": "C:\\Users\\<you>\\.quash\\bin\\quash-mcp\\quash-mcp.exe",
         "env": {
           "QUASH_SIDECAR_CMD": "C:\\Users\\<you>\\.quash\\sidecar\\quash-sidecar\\quash-sidecar.exe",
           "QUASH_TEST_GEN_AGENT_CMD": "C:\\Users\\<you>\\.quash\\test-gen-venv\\Scripts\\python.exe -m test_gen_agent"
         }
       }
     }
   }
   

4. 点击 OK → Apply，启动服务。

**Android Studio：**其 Agent（Gemini Agent Mode）目前仅支持通过 HTTP/Streamable 使用 MCP，不支持 stdio，因此上述配置暂不适用于 Android Studio。

---

5. 进行身份验证

• 如果你设置了 QUASH_API_TOKEN，服务会在启动时自动登录。
• 否则，请让 Agent 进行身份验证：
  • Google（浏览器）：“使用 Quash，运行 auth，模式为 google。”
  • 令牌：“使用 Quash，运行 auth，使用我的令牌 qsh_…。”

随时可通过 about / configure 工具查看状态。

---

6. 准备设备

1. 连接——“使用 Quash，运行 connect。”该工具会检测设备（如果有多个则列出设备），预热引擎，并运行设置健康检查。
2. 完成对应设备类型的设置：
   • Android——如果 connect 报告 "Portal not ready"，请运行 setup_portal：该工具会安装设备端的 Quash Portal 应用并启用其无障碍服务（可重复运行）。如果设备阻止安装，该工具会返回 manual_required，并提供前往 Settings → Accessibility 的操作步骤。
   • iOS 模拟器（macOS）——运行 setup_simulator：为已启动的模拟器构建并启动 WebDriverAgent（无需签名）。
   • 实体 iPhone（iOS，macOS）——运行 setup_device：解析你的 Apple Developer 签名团队（使用 configure signing_team=<TEAMID> 设置，或从钥匙串自动检测），构建并签名 WebDriverAgent，启动 USB 隧道并运行 WebDriverAgent。需要 Xcode、启用开发者模式，并通过 USB 信任 iPhone。

---

7. 使用工具

用自然语言向 Agent 提出要求；Agent 会调用以下工具：

工具	功能	平台
about	服务名称、运行版本、最新版本、更新命令	所有平台
auth	登录（google 浏览器流程或 token）	所有平台
connect	检测/选择设备；检查 adb、Portal、引擎和身份验证状态	所有平台
configure	查看/更改执行和测试生成设置（模型、温度、最大步数、视觉、signing_team）	所有平台
setup_portal	安装 Android Portal 应用并启用无障碍功能（可重复执行）	所有平台
setup_simulator	为已启动的 iOS 模拟器构建并启动 WebDriverAgent	macOS
setup_device	通过 USB 为实体 iPhone 签名并启动 WebDriverAgent	macOS
execute	在设备上运行自然语言测试任务（流式显示进度）	所有平台
generate_test_cases	根据提示词、本地文件或 git 仓库生成测试用例	所有平台
usage	当前套餐、剩余分钟数、功能限制	所有平台
list_apps	列出组织中的应用	所有平台
builds	列出应用的构建版本（版本、标签、是否可安装）	所有平台
install_build	下载构建版本的 APK 并安装到设备上	所有平台
runs	浏览近期运行记录，或获取某次运行的完整报告和分享链接	所有平台
test_cases / suites	浏览测试用例和测试套件	所有平台

典型的首次使用流程：

"Use Quash: connect, then setup_portal if needed."          # Android
"Use Quash: connect, then setup_simulator."                 # iOS simulator (macOS)
"Run this on the device: open Settings and turn on Airplane mode."
"Show me the report for that run."
"Generate test cases for https://github.com/acme/my-app."

---

8. 更新

针对你的平台重新运行安装程序（macOS 使用 curl … | sh，Windows 使用 irm … | iex）， 然后重启 Agent。使用 about 工具确认：它会报告运行版本以及是否存在更新版本。

---

9. 故障排除

• “Portal 未就绪”（Android） → 运行 setup_portal。如果返回 manual_required，请在设置 → 无障碍功能中启用 Mahoraga Portal。
• 找不到 adb / 设备 → 安装 Android platform-tools，确保 adb 位于 PATH 中（Windows：设置 ANDROID_HOME），并确认设备显示在 adb devices 下。
• iOS setup_device 签名失败（macOS） → 使用 configure signing_team=<TEAMID> 设置你的团队，确保已在 Xcode → 设置 → 账户中登录 Apple ID（并且钥匙串中有 Apple Development 证书）， 同时确保 iPhone 已启用开发者模式并受信任。
• 会话已过期 / 未通过身份验证 → 重新运行 auth，或刷新 QUASH_API_TOKEN（生成新令牌会使旧令牌失效）。
• 应用中看不到某次运行 → 该运行所属的组织必须与应用所属组织一致； 检查 execute 结果中的 warning 字段。
• macOS Gatekeeper 警告 → 公共二进制文件使用临时签名；如果被阻止， 请在系统设置 → 隐私与安全性中允许其运行。
• Windows SmartScreen / Defender → 未签名的二进制文件可能会提示 “Windows 已保护你的电脑”；点击更多信息 → 仍要运行，或将 %USERPROFILE%\.quash 添加到 Defender 排除项中。