{
  "markdown": "# Quash MCP\n\nThe Quash MCP server lets an AI agent (Claude Code, Claude Desktop, Cursor, …)\ndrive real mobile-app automation on a connected device: run natural-language test\ntasks, generate test cases from prompts/docs/repos, manage apps & builds, and pull\nback streamed runs and reports — all powered by the Quash (mahoraga) automation\nengine.\n\nThis guide covers installing it on **macOS or Windows**, wiring it into your\nagent, generating an API token, preparing a device, and using every tool.\n\n---\n\n## Platform support\n\n| Platform | Android | iOS (simulator + physical) | Installer |\n|---|:---:|:---:|---|\n| **macOS** (Apple Silicon) | ✅ | ✅ | `install.sh` (`curl … \\| sh`) |\n| **Windows** (x64) | ✅ | ❌ *(Apple toolchain is macOS-only)* | `install.ps1` (`irm … \\| iex`) |\n\n> iOS automation needs Xcode / WebDriverAgent / `devicectl` / `iproxy`, which exist\n> only on macOS — so the iOS tools (`setup_simulator`, `setup_device`) appear in\n> the macOS build only. Windows is Android-only. Linux x86_64 can be built from\n> source but isn't published as a release binary.\n\n---\n\n## 1. Prerequisites\n\n- **macOS 13+ (Apple Silicon)** or **Windows 10/11 (x64)**.\n- **`adb`** on your `PATH` (Android platform-tools) for Android automation. On\n  Windows the installer also detects `%LOCALAPPDATA%\\Android\\Sdk`.\n- **A device:** an Android device/emulator (USB debugging on), or — on macOS — an\n  iOS simulator or a physical iPhone (Developer Mode on, trusted, USB).\n- **A Quash account** to authenticate (step 3 for a token, or browser sign-in in step 5).\n- For iOS on macOS: **Xcode** installed (for the WebDriverAgent build).\n\n> The installer also downloads the automation engine, a bundled test-generation\n> component, and the on-device Android **Portal APK**.\n\n---\n\n## 2. Install\n\nOne command installs everything and auto-registers the server in every supported\nagent config it finds (Claude Code, Claude Desktop, Cursor). Pick your platform:\n\n**macOS**\n```sh\ncurl -fsSL https://raw.githubusercontent.com/Oscorp-HQ/quash-mcp-releases/main/install.sh | sh\n```\n\n**Windows (PowerShell)**\n```powershell\nirm https://raw.githubusercontent.com/Oscorp-HQ/quash-mcp-releases/main/install.ps1 | iex\n```\n\nThis installs the latest release into `~/.quash` (macOS) / `%USERPROFILE%\\.quash`\n(Windows) and **connects to Quash production automatically** — no backend URL to\nconfigure.\n\n> **Cursor users:** after running the installer above (needed for the engine), you can\n> one-click add the MCP server to Cursor:\n>\n> [![Add Quash to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=quash&config=eyJjb21tYW5kIjoiJHt1c2VySG9tZX0vLnF1YXNoL2Jpbi9xdWFzaC1tY3AiLCJlbnYiOnsiUVVBU0hfU0lERUNBUl9DTUQiOiIke3VzZXJIb21lfS8ucXVhc2gvc2lkZWNhci9xdWFzaC1zaWRlY2FyL3F1YXNoLXNpZGVjYXIiLCJRVUFTSF9URVNUX0dFTl9BR0VOVF9DTUQiOiIke3VzZXJIb21lfS8ucXVhc2gvdGVzdC1nZW4tdmVudi9iaW4vcHl0aG9uIC1tIHRlc3RfZ2VuX2FnZW50In19)\n>\n> (The installer already auto-registers Cursor, so this is only needed if you skipped that or removed the entry.)\n\n### Options (env vars)\n\n> **macOS gotcha:** environment variables must go on the piped **`sh`**, *not* on\n> `curl` — a prefix on `curl` is ignored. On Windows, set `$env:…` before the `irm`.\n\n**macOS — wire your token in / pin a version:**\n```sh\n# Token at install time (recommended — see step 3):\ncurl -fsSL https://raw.githubusercontent.com/Oscorp-HQ/quash-mcp-releases/main/install.sh | QUASH_API_TOKEN=qsh_xxxxxxxx sh\n\n# Pin a specific version:\ncurl -fsSL https://raw.githubusercontent.com/Oscorp-HQ/quash-mcp-releases/main/install.sh | QUASH_VERSION=v1.1.0 sh\n```\n\n**Windows — same, via `$env:`:**\n```powershell\n$env:QUASH_API_TOKEN = \"qsh_xxxxxxxx\"\nirm https://raw.githubusercontent.com/Oscorp-HQ/quash-mcp-releases/main/install.ps1 | iex\n```\n\n| Env var | Default | Purpose |\n|---|---|---|\n| `QUASH_API_TOKEN` | _(unset)_ | API token; if set, the MCP signs in automatically on startup |\n| `QUASH_VERSION` | latest | Release tag to install |\n| `QUASH_BACKEND_URL` | production | Override the backend (staging/local) |\n| `QUASH_FORCE` | `0` | `1` forces a full reinstall even if the version matches |\n\nRe-running the installer is safe: it refreshes config and, with `QUASH_FORCE=1`,\nreinstalls the binaries. **Reconnecting the agent does not update the server —\nonly re-running the installer does.**\n\n---\n\n## 3. Generate an API token from the Quash app\n\nThe token lets the MCP authenticate without a browser. (Prefer not to manage a\ntoken? Skip to step 5 and use **Google sign-in** instead.)\n\n1. Open the **Quash desktop app** and sign in.\n2. Go to **Settings → Integrations**.\n3. Click **Generate token** (or regenerate to replace an existing one).\n4. **Copy the token** — it starts with `qsh_`. It's shown once; store it safely.\n\nGenerating a new token **invalidates the previous one**, so update it everywhere\nyou use it. The token is scoped to the organization you're signed into and is\nstored only in your agent's MCP config `env` block — never passed through the chat.\n\n---\n\n## 4. Add it to your agent\n\nThe installer auto-registers the `quash` server, so usually there's nothing to do.\nTo verify or add it manually, the entry looks like this — **use the paths for your\nplatform**:\n\n**macOS**\n```jsonc\n{\n  \"mcpServers\": {\n    \"quash\": {\n      \"type\": \"stdio\",\n      \"command\": \"/Users/<you>/.quash/bin/quash-mcp\",\n      \"env\": {\n        \"QUASH_SIDECAR_CMD\": \"/Users/<you>/.quash/sidecar/quash-sidecar/quash-sidecar\",\n        \"QUASH_TEST_GEN_AGENT_CMD\": \"/Users/<you>/.quash/test-gen-venv/bin/python -m test_gen_agent\",\n        \"QUASH_API_TOKEN\": \"qsh_xxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n**Windows**\n```jsonc\n{\n  \"mcpServers\": {\n    \"quash\": {\n      \"type\": \"stdio\",\n      \"command\": \"C:\\\\Users\\\\<you>\\\\.quash\\\\bin\\\\quash-mcp\\\\quash-mcp.exe\",\n      \"env\": {\n        \"QUASH_SIDECAR_CMD\": \"C:\\\\Users\\\\<you>\\\\.quash\\\\sidecar\\\\quash-sidecar\\\\quash-sidecar.exe\",\n        \"QUASH_API_TOKEN\": \"qsh_xxxxxxxx\",\n        \"ANDROID_HOME\": \"C:\\\\Users\\\\<you>\\\\AppData\\\\Local\\\\Android\\\\Sdk\"\n      }\n    }\n  }\n}\n```\n\nConfig file locations: Claude Code → `~/.claude.json` (macOS) /\n`%USERPROFILE%\\.claude.json` (Windows); Claude Desktop →\n`~/Library/Application Support/Claude/claude_desktop_config.json` /\n`%APPDATA%\\Claude\\claude_desktop_config.json`; Cursor → `~/.cursor/mcp.json` /\n`%USERPROFILE%\\.cursor\\mcp.json`.\n\nAfter editing config, **restart the agent** (or `/mcp` → reconnect in Claude Code).\n\n### JetBrains IDEs (IntelliJ IDEA, PyCharm)\n\nJetBrains AI Assistant supports MCP over stdio. After running the installer (step 2):\n\n1. Open **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**.\n2. **Easiest:** click **Import from Claude** — since the installer already registered Quash\n   in Claude Desktop, the `quash` server is pulled in automatically.\n3. **Or add manually:** click **Add**, then paste this JSON (JetBrains does *not* expand\n   environment variables, so use absolute paths — replace `<you>` with your username):\n\n   **macOS**\n   ```jsonc\n   {\n     \"mcpServers\": {\n       \"quash\": {\n         \"command\": \"/Users/<you>/.quash/bin/quash-mcp\",\n         \"env\": {\n           \"QUASH_SIDECAR_CMD\": \"/Users/<you>/.quash/sidecar/quash-sidecar/quash-sidecar\",\n           \"QUASH_TEST_GEN_AGENT_CMD\": \"/Users/<you>/.quash/test-gen-venv/bin/python -m test_gen_agent\"\n         }\n       }\n     }\n   }\n   ```\n   **Windows**\n   ```jsonc\n   {\n     \"mcpServers\": {\n       \"quash\": {\n         \"command\": \"C:\\\\Users\\\\<you>\\\\.quash\\\\bin\\\\quash-mcp\\\\quash-mcp.exe\",\n         \"env\": {\n           \"QUASH_SIDECAR_CMD\": \"C:\\\\Users\\\\<you>\\\\.quash\\\\sidecar\\\\quash-sidecar\\\\quash-sidecar.exe\",\n           \"QUASH_TEST_GEN_AGENT_CMD\": \"C:\\\\Users\\\\<you>\\\\.quash\\\\test-gen-venv\\\\Scripts\\\\python.exe -m test_gen_agent\"\n         }\n       }\n     }\n   }\n   ```\n4. Click **OK → Apply** to start the server.\n\n> **Android Studio:** its agent (Gemini Agent Mode) currently supports MCP over **HTTP/Streamable\n> only**, not stdio, so the config above does not apply there yet.\n\n---\n\n## 5. Authenticate\n\n- **If you set `QUASH_API_TOKEN`**, the server signs in automatically on startup.\n- **Otherwise**, ask the agent to authenticate:\n  - **Google (browser):** \"Use Quash, run `auth` with mode `google`.\"\n  - **Token:** \"Use Quash, run `auth` with my token `qsh_…`.\"\n\nCheck status anytime with the `about` / `configure` tools.\n\n---\n\n## 6. Prepare the device\n\n1. **Connect** — \"Use Quash, `connect`.\" It detects the device (or lists them if\n   several), warms the engine, and runs a setup health check.\n2. **Finish setup for that device type:**\n   - **Android** — if `connect` reports *\"Portal not ready\"*, run **`setup_portal`**:\n     it installs the on-device Quash Portal app and enables its accessibility\n     service (idempotent). If the device blocks it, it returns `manual_required`\n     with the steps for **Settings → Accessibility**.\n   - **iOS simulator (macOS)** — run **`setup_simulator`**: builds + launches\n     WebDriverAgent for the booted simulator (no signing needed).\n   - **iOS physical iPhone (macOS)** — run **`setup_device`**: resolves your Apple\n     Developer **signing team** (set it with `configure signing_team=<TEAMID>`, or\n     it's auto-detected from your keychain), builds + signs WebDriverAgent, starts\n     the USB tunnel, and launches it. Requires Xcode, Developer Mode on, and the\n     iPhone trusted over USB.\n\n---\n\n## 7. Using the tools\n\nAsk the agent in plain language; it calls these tools:\n\n| Tool | What it does | Platform |\n|---|---|---|\n| `about` | Server name, running version, latest release, update command | all |\n| `auth` | Sign in (`google` browser flow, or `token`) | all |\n| `connect` | Detect/select a device; health-check adb, Portal, engine, auth | all |\n| `configure` | View/change execution + test-gen settings (model, temperature, max steps, vision, `signing_team`) | all |\n| `setup_portal` | Install the Android Portal app + enable accessibility (idempotent) | all |\n| `setup_simulator` | Build + launch WebDriverAgent for a booted iOS simulator | macOS |\n| `setup_device` | Sign + launch WebDriverAgent on a physical iPhone over USB | macOS |\n| `execute` | Run a natural-language test task on the device (streams progress) | all |\n| `generate_test_cases` | Generate test cases from a prompt, local files, or a git repo | all |\n| `usage` | Current plan, remaining minutes, feature limits | all |\n| `list_apps` | List apps in your org | all |\n| `builds` | List builds for an app (version, tag, installable) | all |\n| `install_build` | Download a build's APK and install it on the device | all |\n| `runs` | Browse recent runs, or fetch one run's full report + share link | all |\n| `test_cases` / `suites` | Browse test cases and suites | all |\n\n**Typical first session:**\n\n```\n\"Use Quash: connect, then setup_portal if needed.\"          # Android\n\"Use Quash: connect, then setup_simulator.\"                 # iOS simulator (macOS)\n\"Run this on the device: open Settings and turn on Airplane mode.\"\n\"Show me the report for that run.\"\n\"Generate test cases for https://github.com/acme/my-app.\"\n```\n\n---\n\n## 8. Updating\n\nRe-run the installer for your platform (macOS `curl … | sh`, Windows `irm … | iex`),\nthen **restart the agent**. Confirm with the `about` tool — it reports the running\nversion and whether a newer release exists.\n\n---\n\n## 9. Troubleshooting\n\n- **\"Portal not ready\" (Android)** → run `setup_portal`. If it returns\n  `manual_required`, enable *Mahoraga Portal* under **Settings → Accessibility**.\n- **adb / device not found** → install Android platform-tools, ensure `adb` is on\n  `PATH` (Windows: set `ANDROID_HOME`), and that the device shows under `adb devices`.\n- **iOS `setup_device` signing fails (macOS)** → set your team with\n  `configure signing_team=<TEAMID>`, ensure your Apple ID is signed into\n  **Xcode → Settings → Accounts** (with an *Apple Development* certificate in the\n  keychain), and the iPhone is in Developer Mode + trusted.\n- **Session expired / not authenticated** → re-run `auth`, or refresh\n  `QUASH_API_TOKEN` (generating a new token invalidates the old one).\n- **A run isn't visible in the app** → the run's org must match the app's org;\n  check the `execute` result's `warning` field.\n- **macOS Gatekeeper warning** → public binaries are ad-hoc signed; if blocked,\n  allow them under **System Settings → Privacy & Security**.\n- **Windows SmartScreen / Defender** → unsigned binaries may prompt *\"Windows\n  protected your PC\"*; click **More info → Run anyway**, or add a Defender\n  exclusion for `%USERPROFILE%\\.quash`.\n",
  "bytes": 12556,
  "sha": "917efb192e0ea3b7d9bff100caa511fd6f0e83fb1aeb37bd5f0ca48468cd11a6",
  "repo_slug": "oscorp-hq/quash-mcp-releases",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_abhinav_sai_quash_quash_mcp_0b6fe7ca/readme"
}