Quash MCP User Guide

This guide provides comprehensive instructions on how to install, configure and connect quash-mcp as a Model Context Protocol (MCP) server to various AI development environments and tools. quash-mcp allows AI agents to control Android devices for mobile automation tasks using natural language.

Features

• 🤖 AI-Powered Automation: Control your Android device using plain English

• 📱 Device Connection: Works with emulators and physical devices

• ⚙️ Flexible Configuration: Customize AI model, temperature, vision, reasoning, and more

• 🔄 Real-Time Execution: Live progress streaming during task execution

• 🎯 Suite Execution: Run multiple tasks in sequence with retry logic

• 📊 Usage Tracking: Monitor API costs and token usage

• 🔐 Secure: API key authentication via Quash platform

Installation

Requirements

Before you begin, ensure you meet the following requirements:

• Python 3.11+: Required for the quash-mcp server.

• Android Device: An Android emulator or a physical device with USB debugging enabled.

• Quash API Key: Obtain this from mcp.quashbugs.com.

Steps

1. Install quash-mcp: quash-mcp is installed directly via pip. All necessary dependencies, including ADB tools and the Quash Portal APK, are automatically handled.

pip install quash-mcp

1. To upgrade to the latest version, you can run:

pip install --upgrade quash-mcp

(Note: AI execution happens on the Quash backend, keeping the client lightweight and proprietary logic protected.)

Quick Start

1. Get Your API Key

• Visit mcp.quashbugs.com (or your deployment URL).

• Sign in with Google.

• Create or Join an organization.

• Go to Dashboard → API Keys.

• Create a new API key.

2. Add to Your MCP Host

quash-mcp works by exposing its functionalities to any MCP-compatible host. You configure your host to use python3 -m quash_mcp, which ensures compatibility across various Python environments.

Manual Configuration (Recommended)

This method involves adding a JSON snippet to your MCP host's configuration file. This is the most robust way to ensure your host can find and utilize quash-mcp.

Config file locations:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json

• Claude Desktop (Linux): ~/.config/claude/claude_desktop_config.json

• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json

• Claude Code: ~/.claude.json (project-specific under projects.<path>.mcpServers)

JSON Snippet to Add:

{ "mcpServers": { "quash": { "command": "python3", "args": ["-m", "quash_mcp"] } } }

CLI Configuration (If Supported by Host)

Some MCP hosts provide a command-line interface to add servers, simplifying the configuration process.

• Claude Code:

claude mcp add quash quash-mcp

• Gemini CLI:

gemini mcp add quash quash-mcp

Alternative: Direct Command

If the quash-mcp executable is directly available in your system's PATH, you can use a simpler configuration. However, the manual configuration with python3 -m quash_mcp is generally more reliable.

{ "mcpServers": { "quash": { "command": "quash-mcp" } } }

After configuring, restart your MCP host (e.g., Claude Desktop, Gemini CLI) for the changes to take effect.

3. Prepare Your Environment

Before you start automating tasks, ensure your quash-mcp setup is ready and connected to your device. You can do this by asking your AI assistant to run the build and connect tools.

• Run the build tool: This verifies and sets up all necessary dependencies.

User: "Setup Quash on my machine" → Runs build tool → Returns: All dependencies installed ✓

• Run the connect tool: This connects quash-mcp to your Android device or emulator.

User: "Connect to my Android emulator" → Runs connect tool → Returns: Connected to emulator-5554 ✓

(Follow any on-screen prompts to enable the Quash Portal accessibility service on your device if requested.)

Once these steps are successfully completed, your quash-mcp is ready for automation.

4. Configure Quash API Key

Before quash-mcp can interact with the Quash backend or perform any tasks, you need to configure it with your Quash API key. Once configured, this API key will be persistently stored and used for all subsequent quash-mcp executions until it is explicitly changed again.

Parameters:

• quash_api_key: Your Quash API key for authentication and access.

Example Usage:

Configure Quash with my API key mhg_xxx, use Claude Sonnet 4, and enable vision

5. Start Automating

Once quash-mcp is configured with your MCP host, you can ask your AI assistant to perform mobile automation tasks using natural language. The AI will automatically leverage the available quash-mcp tools.

Available Tools

quash-mcp exposes the following tools to your AI assistant:

Build

Setup and verify all dependencies required for Quash mobile automation. Checks Python version, ADB installation, Quash package, and Portal APK. Attempts to auto-install missing dependencies where possible.

Example Usage:

Can you run the build tool to setup my system for Quash?

Connect

Connect to an Android device or emulator. Auto-detects single device or allows selection from multiple devices. Verifies connectivity and checks/installs Quash Portal accessibility service.

Parameters:

• device_serial (optional): The serial number of the device to connect to. If omitted, quash-mcp will attempt to auto-detect a single connected device.

Example Usage:

Connect to my Android device

Connect to emulator-5554

Configure

Configure agent execution parameters.

Parameters:

• quash_api_key: Your Quash API key from the web portal

• model: LLM model (e.g., "anthropic/claude-sonnet-4", "openai/gpt-4o")

• temperature: 0-2 (default: 0.2)

• max_steps: Maximum execution steps (default: 15)

• vision: Enable screenshots (default: false)

• reasoning: Enable multi-step planning (default: false)

• reflection: Enable self-improvement (default: false)

• debug: Verbose logging (default: false)

Example:

Configure Quash with my API key mhg_xxx, use Claude Sonnet 4, and enable vision

Execute

Execute a mobile automation task on the connected Android device. Takes natural language instructions and performs the task using AI agents. Provides live progress updates during execution.

Parameters:

• task: Natural language description of the task to perform (e.g., Open Settings and navigate to WiFi).

Example Usage:

Execute task: Open Settings and navigate to WiFi settings

Complete Workflow Example

This example demonstrates a typical interaction flow with quash-mcp through an AI assistant:

User: "Setup Quash on my machine" → Runs build tool → Returns: All dependencies installed ✓

User: "Connect to my Android emulator" → Runs connect tool → Returns: Connected to emulator-5554 ✓

User: "Configure to use Claude Sonnet 4 with vision and my API key is mhg_xxx..." → Runs configure tool → Returns: Configuration set ✓

User: "Execute task: Open Instagram and go to my profile" → Runs execute tool with live streaming → Returns: Task completed ✓

User: "Show me my usage statistics" → Runs usage tool → Returns: Total cost: $0.15, 10 executions ✓

Troubleshooting

• "No devices found"

  • Start your Android emulator via Android Studio > AVD Manager.

  • Connect your physical device with USB debugging enabled.

  • For WiFi debugging: adb tcpip 5555 && adb connect <device-ip>:5555.

• "Portal not ready"

  • The connect tool automatically installs the Quash Portal APK.

  • If it fails, manually enable the Quash Portal accessibility service in your device's Settings > Accessibility.

• "Invalid API key"

  • Ensure you've run configure with a valid API key obtained from mcp.quashbugs.com.

  • Make sure you have enough credits in your organization.

  • Check your API key hasn't been revoked in the web portal.

• LLM does not use quash-mcp tools:

  • Ensure quash-mcp is correctly configured as an MCP server in your client's settings.

  • Review your client's documentation on how to enable or prioritize external tools/providers.

  • Refine your prompts to clearly indicate the need for mobile automation actions.