# Mahoraga MCP - AI-Powered Mobile Automation
A Model Context Protocol (MCP) server for mobile automation testing with Mahoraga. 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 Mahoraga platform
## Installation
```bash
pip install mahoraga-mcp
```
All dependencies (including ADB tools, LLM frameworks, and image processing) are automatically installed.
## Quick Start
### 1. Get Your API Key
1. Visit [mahoraga.app](https://mahoraga.app) (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
Mahoraga MCP works with any MCP-compatible host. Use your host's CLI to add it:
#### Claude Code
```bash
claude mcp add mahoraga mahoraga-mcp
```
#### Amp
```bash
amp mcp add mahoraga -- mahoraga-mcp
```
#### VS Code (Cline)
```bash
code --add-mcp '{"name":"mahoraga","command":"mahoraga-mcp"}'
```
#### Manual Configuration
If your MCP host doesn't have a CLI, manually add to config file:
**Config file locations:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"mahoraga": {
"command": "mahoraga-mcp"
}
}
}
```
Then restart your MCP host.
### 3. Start Automating
Ask your AI assistant (via your MCP host):
```
"Setup Mahoraga 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 Mahoraga?
```
### 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:**
- `mahoraga_api_key`: Your Mahoraga 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 Mahoraga 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 Mahoraga usage statistics
```
## Complete Workflow Example
```
User: "Setup Mahoraga 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
- **Mahoraga API Key** - Get from [mahoraga.app](https://mahoraga.app)
Dependencies automatically installed:
- Android Debug Bridge (ADB) - via `adbutils`
- Mahoraga Portal APK - via `apkutils`
- LLM frameworks - via `llama-index`
- Image processing - via `pillow`
## Architecture
```
mahoraga-mcp/
├── src/
│ ├── server.py # Main MCP server entry point
│ ├── backend_client.py # API communication with Mahoraga platform
│ ├── llm_wrapper.py # LLM integration layer
│ ├── state.py # Session state management
│ ├── usage_tracker.py # Usage and cost tracking
│ └── tools/
│ ├── build.py # Dependency checker and installer
│ ├── connect.py # Device connectivity
│ ├── configure.py # Agent configuration
│ ├── execute.py # Task execution
│ ├── runsuite.py # Suite execution
│ └── usage.py # Usage statistics
└── 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 Mahoraga Portal accessibility service in Settings > Accessibility
**"Invalid API key"**
- Make sure you've run `configure` with a valid API key from mahoraga.app
- 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": "mahoraga-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "ai, android, mahoraga, mcp, mobile-automation, testing",
"author": null,
"author_email": "Mahoraga Team <hello@mahoraga.app>",
"download_url": "https://files.pythonhosted.org/packages/d8/6f/180d75c8542f9e8a8c8004aaaf2d2fd13996cb0850295c95d64d1bba5b85/mahoraga_mcp-0.2.0.tar.gz",
"platform": null,
"description": "# Mahoraga MCP - AI-Powered Mobile Automation\n\nA Model Context Protocol (MCP) server for mobile automation testing with Mahoraga. 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 Mahoraga platform\n\n## Installation\n\n```bash\npip install mahoraga-mcp\n```\n\nAll dependencies (including ADB tools, LLM frameworks, and image processing) are automatically installed.\n\n## Quick Start\n\n### 1. Get Your API Key\n\n1. Visit [mahoraga.app](https://mahoraga.app) (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\nMahoraga MCP works with any MCP-compatible host. Use your host's CLI to add it:\n\n#### Claude Code\n```bash\nclaude mcp add mahoraga mahoraga-mcp\n```\n\n#### Amp\n```bash\namp mcp add mahoraga -- mahoraga-mcp\n```\n\n#### VS Code (Cline)\n```bash\ncode --add-mcp '{\"name\":\"mahoraga\",\"command\":\"mahoraga-mcp\"}'\n```\n\n#### Manual Configuration\n\nIf your MCP host doesn't have a CLI, manually add to config file:\n\n**Config file locations:**\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Linux**: `~/.config/claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"mahoraga\": {\n \"command\": \"mahoraga-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 Mahoraga 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 Mahoraga?\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- `mahoraga_api_key`: Your Mahoraga 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 Mahoraga 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 Mahoraga usage statistics\n```\n\n## Complete Workflow Example\n\n```\nUser: \"Setup Mahoraga 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- **Mahoraga API Key** - Get from [mahoraga.app](https://mahoraga.app)\n\nDependencies automatically installed:\n- Android Debug Bridge (ADB) - via `adbutils`\n- Mahoraga Portal APK - via `apkutils`\n- LLM frameworks - via `llama-index`\n- Image processing - via `pillow`\n\n## Architecture\n\n```\nmahoraga-mcp/\n\u251c\u2500\u2500 src/\n\u2502 \u251c\u2500\u2500 server.py # Main MCP server entry point\n\u2502 \u251c\u2500\u2500 backend_client.py # API communication with Mahoraga platform\n\u2502 \u251c\u2500\u2500 llm_wrapper.py # LLM integration layer\n\u2502 \u251c\u2500\u2500 state.py # Session state management\n\u2502 \u251c\u2500\u2500 usage_tracker.py # Usage and cost tracking\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\n\u2502 \u251c\u2500\u2500 runsuite.py # Suite execution\n\u2502 \u2514\u2500\u2500 usage.py # Usage statistics\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 Mahoraga Portal accessibility service in Settings > Accessibility\n\n**\"Invalid API key\"**\n- Make sure you've run `configure` with a valid API key from mahoraga.app\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 Mahoraga - AI-powered mobile automation agent",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://docs.mahoraga.app",
"Homepage": "https://mahoraga.app",
"Issues": "https://github.com/mahoraga/mahoraga-mcp/issues",
"Repository": "https://github.com/mahoraga/mahoraga-mcp"
},
"split_keywords": [
"ai",
" android",
" mahoraga",
" mcp",
" mobile-automation",
" testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f17c1820ed25aca47fe67354278e007cfddf11cd52bbb65dd6d0f9e37e31f955",
"md5": "3238c3ca2ba2f99c5ac39012b4e0507c",
"sha256": "d4c2bbb5278f68b9e31fe07129138e5bd37c070932a6cf444c517d539316b52d"
},
"downloads": -1,
"filename": "mahoraga_mcp-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3238c3ca2ba2f99c5ac39012b4e0507c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 28900,
"upload_time": "2025-10-11T12:49:53",
"upload_time_iso_8601": "2025-10-11T12:49:53.603623Z",
"url": "https://files.pythonhosted.org/packages/f1/7c/1820ed25aca47fe67354278e007cfddf11cd52bbb65dd6d0f9e37e31f955/mahoraga_mcp-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d86f180d75c8542f9e8a8c8004aaaf2d2fd13996cb0850295c95d64d1bba5b85",
"md5": "9807f33f008f9e72fab52cf52ec90b9a",
"sha256": "069addf74723d1cc1d0b41690d17ad877cbca97b04ed9c736f42ae72f7b8f954"
},
"downloads": -1,
"filename": "mahoraga_mcp-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "9807f33f008f9e72fab52cf52ec90b9a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 25146,
"upload_time": "2025-10-11T12:49:54",
"upload_time_iso_8601": "2025-10-11T12:49:54.915734Z",
"url": "https://files.pythonhosted.org/packages/d8/6f/180d75c8542f9e8a8c8004aaaf2d2fd13996cb0850295c95d64d1bba5b85/mahoraga_mcp-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-11 12:49:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mahoraga",
"github_project": "mahoraga-mcp",
"github_not_found": true,
"lcname": "mahoraga-mcp"
}
JSON
