Quash — Mobile App Automation

Quash MCP

Quash MCP サーバーを使うと、AI エージェント（Claude Code、Claude Desktop、Cursor など）が、接続されたデバイス上で実際のモバイルアプリを自動操作できます。自然言語によるテストタスクの実行、プロンプト／ドキュメント／リポジトリからのテストケース生成、アプリやビルドの管理、ストリーミング実行結果やレポートの取得が可能です。すべて Quash（mahoraga）自動化エンジンによって実現します。

このガイドでは、macOS または Windows へのインストール、エージェントへの接続、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 の自動操作には、PATH 上に adb（Android platform-tools）が必要です。Windows では、インストーラーは %LOCALAPPDATA%\Android\Sdk も検出します。
• デバイス： Android デバイス／エミュレーター（USB デバッグを有効化）、または macOS の場合は iOS シミュレーターか実機の iPhone（デベロッパーモードを有効化し、信頼済みで、USB 接続されていること）。
• 認証用の Quash アカウント（トークンを使う場合はステップ 3、またはステップ 5 でブラウザーからサインイン）。
• macOS での iOS 利用には、Xcode がインストールされている必要があります（WebDriverAgent のビルドに使用）。

インストーラーは、自動化エンジン、同梱のテスト生成コンポーネント、デバイス上で動作する Android Portal APK もダウンロードします。

---

2. インストール

1 つのコマンドですべてをインストールし、検出したすべての対応エージェントの設定にサーバーを自動登録します（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 に付けた環境変数は無視されます。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	バックエンドを上書きします（ステージング／ローカル）
QUASH_FORCE	0	1 にすると、バージョンが一致していても完全に再インストールします

インストーラーは何度実行しても問題ありません。設定が更新され、QUASH_FORCE=1 を指定するとバイナリが再インストールされます。エージェントを再接続してもサーバーは更新されません。更新するには、インストーラーを再実行してください。

---

3. Quash アプリから API トークンを生成する

このトークンを使うと、MCP はブラウザーを使わずに認証できます。（トークンの管理を避けたい場合は、ステップ 5 に進み、代わりに Google サインインを使用してください。）

1. Quash デスクトップアプリを開いてサインインします。
2. Settings → Integrationsに移動します。
3. Generate tokenをクリックします（既存のトークンを置き換える場合は再生成します）。
4. トークンをコピーします。qsh_ で始まります。一度だけ表示されるため、安全な場所に保管してください。

新しいトークンを生成すると、以前のトークンは無効になります。そのため、使用しているすべての場所で更新してください。トークンの適用範囲は、サインインしている組織に限定されます。また、エージェントの MCP 設定の env ブロックにのみ保存され、チャットを介して渡されることはありません。

---

4. エージェントに追加する

インストーラーが 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。

設定を編集した後、エージェントを再起動します（または、Claude Code で /mcp → 再接続）。

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： 現在、そのエージェント（Gemini Agent Mode）が対応している MCP は HTTP/Streamable のみで、stdio には対応していないため、上記の設定はまだ適用できません。

---

5. 認証する

• QUASH_API_TOKENを設定した場合、起動時にサーバーが自動的にサインインします。
• 設定していない場合は、エージェントに認証を依頼します。
  • Google（ブラウザー）：「Quash を使用して、mode google で auth を実行してください。」
  • トークン：「Quash を使用して、トークン qsh_… で auth を実行してください。」

about ／ configure ツールを使うと、いつでも状態を確認できます。

---

6. デバイスを準備する

1. 接続する —「Quash を使用して、connect を実行してください。」デバイスを検出し（複数ある場合は一覧表示）、エンジンを準備して、セットアップのヘルスチェックを実行します。
2. デバイスの種類に応じたセットアップを完了します：
   • Android — connect で "Portal not ready" と報告された場合は、**setup_portal**を実行します。デバイスに Quash Portal アプリをインストールし、そのユーザー補助サービスを有効にします（冪等です）。デバイスによってブロックされた場合は、Settings → Accessibilityでの手順とともに manual_required が返されます。
   • iOS シミュレーター（macOS） — **setup_simulator**を実行します。起動済みシミュレーター用の WebDriverAgent をビルドして起動します（署名は不要です）。
   • iOS の物理 iPhone（macOS） — setup_deviceを実行します。Apple Developer の署名チームを特定し（configure signing_team=<TEAMID> で設定するか、キーチェーンから自動検出されます）、WebDriverAgent をビルドして署名し、USB トンネルを起動して、WebDriverAgent を起動します。Xcode、Developer Mode の有効化、および USB 経由で iPhone を信頼済みにすることが必要です。

---

7. ツールの使用

エージェントに平易な言葉で依頼すると、エージェントが以下のツールを呼び出します。

ツール	機能	プラットフォーム
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）、 その後 エージェントを再起動してください。about ツールで確認できます。実行中の バージョンと、より新しいリリースがあるかどうかが表示されます。

---

9. トラブルシューティング

• 「Portal not ready」（Android） → setup_portal を実行してください。manual_required が返された場合は、Settings → Accessibility で Mahoraga Portal を有効にしてください。
• adb／デバイスが見つからない → Android platform-tools をインストールし、PATH に adb が設定されていること（Windows：ANDROID_HOME を設定）、およびデバイスが adb devices に表示されていることを確認してください。
• iOS setup_device の署名に失敗する（macOS） → configure signing_team=<TEAMID> でチームを設定し、Apple Development 証明書がキーチェーンにある状態で、Apple ID が Xcode → Settings → Accounts にサインインしていること、また iPhone がデベロッパーモードで信頼済みであることを確認してください。
• セッションの期限切れ／未認証 → auth を再実行するか、QUASH_API_TOKEN を更新してください（新しいトークンを生成すると古いトークンは無効になります）。
• アプリに実行結果が表示されない → 実行の組織がアプリの組織と一致している必要があります。execute の結果にある warning フィールドを確認してください。
• macOS Gatekeeper の警告 → 公開バイナリはアドホック署名されています。ブロックされた場合は、System Settings → Privacy & Security で許可してください。
• Windows SmartScreen／Defender → 署名されていないバイナリでは "Windows protected your PC" と表示されることがあります。More info → Run anyway をクリックするか、%USERPROFILE%\.quash を Defender の除外対象に追加してください。