| Name | quash-mcp JSON |
| Version |
0.2.11
JSON |
| download |
| home_page | None |
| Summary | Model Context Protocol server for Quash - AI-powered mobile automation agent |
| upload_time | 2025-10-22 17:33:18 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
ai
android
mcp
mobile-automation
quash
testing
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Quash MCP - AI-Powered Mobile Automation
A Model Context Protocol (MCP) server for mobile automation testing with Quash. Control Android devices and run automated tests from **any MCP-compatible host** 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
```bash
pip install quash-mcp
```
All dependencies (including ADB tools and device connectivity) are automatically installed. **AI execution happens on the Quash backend**, keeping the client lightweight and proprietary logic protected.
## Quick Start
### 1. Get Your API Key
1. Visit [quashbugs.com/mcp](http://13.220.180.140.nip.io/) (or your deployment URL)
2. Sign in with Google
3. Go to Dashboard → API Keys
4. Create a new API key
### 2. Add to Your MCP Host
Quash MCP works with any MCP-compatible host. Configure it to use `python3 -m quash_mcp` which works across all Python environments:
#### Manual Configuration (Recommended)
Add to your MCP host's config file:
**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
{
"mcpServers": {
"quash": {
"command": "python3",
"args": ["-m", "quash_mcp"]
}
}
}
```
**Why `python3 -m quash_mcp`?**
- Works in any Python environment (conda, venv, system)
- No PATH configuration needed
- Uses whichever Python has quash-mcp installed
#### CLI Configuration (If Supported by Host)
Some MCP hosts might provide a command-line interface to add servers.
**Examples:**
- **Claude Code:**
```bash
claude mcp add quash quash-mcp
```
- **Gemini CLI:**
```bash
gemini mcp add quash quash-mcp
```
#### Alternative: Direct Command (if in PATH)
If `quash-mcp` is in your PATH:
```json
{
"mcpServers": {
"quash": {
"command": "quash-mcp"
}
}
}
```
Then restart your MCP host.
### 3. Start Automating
Ask your AI assistant (via your MCP host):
```
"Setup Quash and connect to my Android device"
"Configure with my API key: mhg_xxxx..."
"Execute task: Open Settings and enable WiFi"
```
## Available Tools
### 1. `build`
Setup and verify all dependencies.
**Example:**
```
Can you run the build tool to setup my system for Quash?
```
### 2. `connect`
Connect to an Android device or emulator.
**Parameters:**
- `device_serial` (optional): Device serial number
**Example:**
```
Connect to my Android device
```
### 3. `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
```
### 4. `execute`
Run an automation task on the device.
**Parameters:**
- `task`: Natural language task description
**Example:**
```
Execute task: Open Settings and navigate to WiFi settings
```
### 5. `runsuite`
Execute multiple tasks in sequence with retry logic.
**Parameters:**
- `suite_name`: Name of the test suite
- `tasks`: Array of tasks with retry and failure handling options
**Example:**
```
Run a test suite with these tasks: [
{"prompt": "Open Settings", "type": "setup"},
{"prompt": "Enable WiFi", "type": "test", "retries": 2},
{"prompt": "Close Settings", "type": "teardown"}
]
```
### 6. `usage`
View API usage statistics and costs.
**Example:**
```
Show me my Quash usage statistics
```
## Complete Workflow Example
```
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 ✓
```
## Requirements
- **Python 3.11+** - Required for the MCP server
- **Android Device** - Emulator or physical device with USB debugging enabled
- **Quash API Key** - Get from [quashbugs.com/mcp](http://13.220.180.140.nip.io/)
Dependencies automatically installed:
- Android Debug Bridge (ADB) - via `adbutils`
- Quash Portal APK - via `apkutils`
- MCP protocol support - via `mcp`
- HTTP client - via `httpx`
## Architecture
**v0.2.0 uses a client-server architecture:**
- **Client (quash-mcp)**: Lightweight MCP server handling device connections and API calls
- **Server (Quash backend)**: Proprietary AI execution engine (LLMs, agents, pricing logic)
```
quash-mcp/
├── quash_mcp/
│ ├── __main__.py # Module entry point for python -m
│ ├── server.py # Main MCP server entry point
│ ├── backend_client.py # API communication with Quash backend
│ ├── state.py # Session state management
│ └── tools/
│ ├── build.py # Dependency checker and installer
│ ├── connect.py # Device connectivity
│ ├── configure.py # Agent configuration
│ ├── execute.py # Task execution (calls backend API)
│ ├── runsuite.py # Suite execution (calls backend API)
│ └── usage.py # Usage statistics (from backend)
└── pyproject.toml
```
## Troubleshooting
**"No devices found"**
- Start Android emulator via Android Studio > AVD Manager
- Connect 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 Portal APK
- If it fails, manually enable the Quash Portal accessibility service in Settings > Accessibility
**"Invalid API key"**
- Make sure you've run `configure` with a valid API key from quashbugs.com
- API keys start with `mhg_` prefix
- Check your API key hasn't been revoked in the web portal
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "quash-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "ai, android, mcp, mobile-automation, quash, testing",
"author": null,
"author_email": "Quash Team <hello@quashbugs.com>",
"download_url": "https://files.pythonhosted.org/packages/d3/9f/791b2cd21b13804cc09ea3d1987b9516a510db72c3c4b42146ed040beacc/quash_mcp-0.2.11.tar.gz",
"platform": null,
"description": "# Quash MCP - AI-Powered Mobile Automation\n\nA Model Context Protocol (MCP) server for mobile automation testing with Quash. Control Android devices and run automated tests from **any MCP-compatible host** using natural language.\n\n## Features\n\n- \ud83e\udd16 **AI-Powered Automation**: Control your Android device using plain English\n- \ud83d\udcf1 **Device Connection**: Works with emulators and physical devices\n- \u2699\ufe0f **Flexible Configuration**: Customize AI model, temperature, vision, reasoning, and more\n- \ud83d\udd04 **Real-Time Execution**: Live progress streaming during task execution\n- \ud83c\udfaf **Suite Execution**: Run multiple tasks in sequence with retry logic\n- \ud83d\udcca **Usage Tracking**: Monitor API costs and token usage\n- \ud83d\udd10 **Secure**: API key authentication via Quash platform\n\n## Installation\n\n```bash\npip install quash-mcp\n```\n\nAll dependencies (including ADB tools and device connectivity) are automatically installed. **AI execution happens on the Quash backend**, keeping the client lightweight and proprietary logic protected.\n\n## Quick Start\n\n### 1. Get Your API Key\n\n1. Visit [quashbugs.com/mcp](http://13.220.180.140.nip.io/) (or your deployment URL)\n2. Sign in with Google\n3. Go to Dashboard \u2192 API Keys\n4. Create a new API key\n\n### 2. Add to Your MCP Host\n\nQuash MCP works with any MCP-compatible host. Configure it to use `python3 -m quash_mcp` which works across all Python environments:\n\n#### Manual Configuration (Recommended)\n\nAdd to your MCP host's config file:\n\n**Config file locations:**\n- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Claude Desktop (Linux)**: `~/.config/claude/claude_desktop_config.json`\n- **Claude Desktop (Windows)**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Claude Code**: `~/.claude.json` (project-specific under `projects.<path>.mcpServers`)\n\n```json\n{\n \"mcpServers\": {\n \"quash\": {\n \"command\": \"python3\",\n \"args\": [\"-m\", \"quash_mcp\"]\n }\n }\n}\n```\n\n**Why `python3 -m quash_mcp`?**\n- Works in any Python environment (conda, venv, system)\n- No PATH configuration needed\n- Uses whichever Python has quash-mcp installed\n\n#### CLI Configuration (If Supported by Host)\n\nSome MCP hosts might provide a command-line interface to add servers.\n\n**Examples:**\n\n- **Claude Code:**\n ```bash\n claude mcp add quash quash-mcp\n ```\n\n- **Gemini CLI:**\n ```bash\n gemini mcp add quash quash-mcp\n ```\n\n#### Alternative: Direct Command (if in PATH)\n\nIf `quash-mcp` is in your PATH:\n\n```json\n{\n \"mcpServers\": {\n \"quash\": {\n \"command\": \"quash-mcp\"\n }\n }\n}\n```\n\nThen restart your MCP host.\n\n### 3. Start Automating\n\nAsk your AI assistant (via your MCP host):\n\n```\n\"Setup Quash and connect to my Android device\"\n\"Configure with my API key: mhg_xxxx...\"\n\"Execute task: Open Settings and enable WiFi\"\n```\n\n## Available Tools\n\n### 1. `build`\nSetup and verify all dependencies.\n\n**Example:**\n```\nCan you run the build tool to setup my system for Quash?\n```\n\n### 2. `connect`\nConnect to an Android device or emulator.\n\n**Parameters:**\n- `device_serial` (optional): Device serial number\n\n**Example:**\n```\nConnect to my Android device\n```\n\n### 3. `configure`\nConfigure agent execution parameters.\n\n**Parameters:**\n- `quash_api_key`: Your Quash API key from the web portal\n- `model`: LLM model (e.g., \"anthropic/claude-sonnet-4\", \"openai/gpt-4o\")\n- `temperature`: 0-2 (default: 0.2)\n- `max_steps`: Maximum execution steps (default: 15)\n- `vision`: Enable screenshots (default: false)\n- `reasoning`: Enable multi-step planning (default: false)\n- `reflection`: Enable self-improvement (default: false)\n- `debug`: Verbose logging (default: false)\n\n**Example:**\n```\nConfigure Quash with my API key mhg_xxx, use Claude Sonnet 4, and enable vision\n```\n\n### 4. `execute`\nRun an automation task on the device.\n\n**Parameters:**\n- `task`: Natural language task description\n\n**Example:**\n```\nExecute task: Open Settings and navigate to WiFi settings\n```\n\n### 5. `runsuite`\nExecute multiple tasks in sequence with retry logic.\n\n**Parameters:**\n- `suite_name`: Name of the test suite\n- `tasks`: Array of tasks with retry and failure handling options\n\n**Example:**\n```\nRun a test suite with these tasks: [\n {\"prompt\": \"Open Settings\", \"type\": \"setup\"},\n {\"prompt\": \"Enable WiFi\", \"type\": \"test\", \"retries\": 2},\n {\"prompt\": \"Close Settings\", \"type\": \"teardown\"}\n]\n```\n\n### 6. `usage`\nView API usage statistics and costs.\n\n**Example:**\n```\nShow me my Quash usage statistics\n```\n\n## Complete Workflow Example\n\n```\nUser: \"Setup Quash on my machine\"\n\u2192 Runs build tool\n\u2192 Returns: All dependencies installed \u2713\n\nUser: \"Connect to my Android emulator\"\n\u2192 Runs connect tool\n\u2192 Returns: Connected to emulator-5554 \u2713\n\nUser: \"Configure to use Claude Sonnet 4 with vision and my API key is mhg_xxx...\"\n\u2192 Runs configure tool\n\u2192 Returns: Configuration set \u2713\n\nUser: \"Execute task: Open Instagram and go to my profile\"\n\u2192 Runs execute tool with live streaming\n\u2192 Returns: Task completed \u2713\n\nUser: \"Show me my usage statistics\"\n\u2192 Runs usage tool\n\u2192 Returns: Total cost: $0.15, 10 executions \u2713\n```\n\n## Requirements\n\n- **Python 3.11+** - Required for the MCP server\n- **Android Device** - Emulator or physical device with USB debugging enabled\n- **Quash API Key** - Get from [quashbugs.com/mcp](http://13.220.180.140.nip.io/)\n\nDependencies automatically installed:\n- Android Debug Bridge (ADB) - via `adbutils`\n- Quash Portal APK - via `apkutils`\n- MCP protocol support - via `mcp`\n- HTTP client - via `httpx`\n\n## Architecture\n\n**v0.2.0 uses a client-server architecture:**\n- **Client (quash-mcp)**: Lightweight MCP server handling device connections and API calls\n- **Server (Quash backend)**: Proprietary AI execution engine (LLMs, agents, pricing logic)\n\n```\nquash-mcp/\n\u251c\u2500\u2500 quash_mcp/\n\u2502 \u251c\u2500\u2500 __main__.py # Module entry point for python -m\n\u2502 \u251c\u2500\u2500 server.py # Main MCP server entry point\n\u2502 \u251c\u2500\u2500 backend_client.py # API communication with Quash backend\n\u2502 \u251c\u2500\u2500 state.py # Session state management\n\u2502 \u2514\u2500\u2500 tools/\n\u2502 \u251c\u2500\u2500 build.py # Dependency checker and installer\n\u2502 \u251c\u2500\u2500 connect.py # Device connectivity\n\u2502 \u251c\u2500\u2500 configure.py # Agent configuration\n\u2502 \u251c\u2500\u2500 execute.py # Task execution (calls backend API)\n\u2502 \u251c\u2500\u2500 runsuite.py # Suite execution (calls backend API)\n\u2502 \u2514\u2500\u2500 usage.py # Usage statistics (from backend)\n\u2514\u2500\u2500 pyproject.toml\n```\n\n## Troubleshooting\n\n**\"No devices found\"**\n- Start Android emulator via Android Studio > AVD Manager\n- Connect physical device with USB debugging enabled\n- For WiFi debugging: `adb tcpip 5555 && adb connect <device-ip>:5555`\n\n**\"Portal not ready\"**\n- The `connect` tool automatically installs the Portal APK\n- If it fails, manually enable the Quash Portal accessibility service in Settings > Accessibility\n\n**\"Invalid API key\"**\n- Make sure you've run `configure` with a valid API key from quashbugs.com\n- API keys start with `mhg_` prefix\n- Check your API key hasn't been revoked in the web portal\n\n## License\n\nMIT",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Context Protocol server for Quash - AI-powered mobile automation agent",
"version": "0.2.11",
"project_urls": {
"Documentation": "https://docs.quashbugs.com",
"Homepage": "https://quashbugs.com",
"Issues": "https://github.com/quash/quash-mcp/issues",
"Repository": "https://github.com/quash/quash-mcp"
},
"split_keywords": [
"ai",
" android",
" mcp",
" mobile-automation",
" quash",
" testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9e9423f225b81a9596a09b6eedd7506aa1be6049a625724eac72f6802e232931",
"md5": "d015c59de92675dc3b864d45b43c6e68",
"sha256": "c9dc5a1fba7541710312ca528b280430a8c95b4f60ee0c6b7df4f43aa0fd2985"
},
"downloads": -1,
"filename": "quash_mcp-0.2.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d015c59de92675dc3b864d45b43c6e68",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 41916,
"upload_time": "2025-10-22T17:33:17",
"upload_time_iso_8601": "2025-10-22T17:33:17.330075Z",
"url": "https://files.pythonhosted.org/packages/9e/94/23f225b81a9596a09b6eedd7506aa1be6049a625724eac72f6802e232931/quash_mcp-0.2.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d39f791b2cd21b13804cc09ea3d1987b9516a510db72c3c4b42146ed040beacc",
"md5": "6b1180903b96656f2a1f1ca193f1e1e4",
"sha256": "ebb3cfc142e4a8107fa0dd871c72b65008221705987d19965e3603f89ccee977"
},
"downloads": -1,
"filename": "quash_mcp-0.2.11.tar.gz",
"has_sig": false,
"md5_digest": "6b1180903b96656f2a1f1ca193f1e1e4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 35369,
"upload_time": "2025-10-22T17:33:18",
"upload_time_iso_8601": "2025-10-22T17:33:18.862934Z",
"url": "https://files.pythonhosted.org/packages/d3/9f/791b2cd21b13804cc09ea3d1987b9516a510db72c3c4b42146ed040beacc/quash_mcp-0.2.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 17:33:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quash",
"github_project": "quash-mcp",
"github_not_found": true,
"lcname": "quash-mcp"
}
