{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/icon.png\" alt=\"mobile-device-mcp\" width=\"128\" height=\"128\" />\n</p>\n\n<h1 align=\"center\">mobile-device-mcp</h1>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/mobile-device-mcp\"><img src=\"https://img.shields.io/npm/v/mobile-device-mcp\" alt=\"npm version\" /></a>\n  <a href=\"https://www.npmjs.com/package/mobile-device-mcp\"><img src=\"https://img.shields.io/npm/dm/mobile-device-mcp\" alt=\"npm downloads\" /></a>\n  <a href=\"https://github.com/saranshbamania/mobile-device-mcp\"><img src=\"https://img.shields.io/github/stars/saranshbamania/mobile-device-mcp\" alt=\"GitHub stars\" /></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/License-BSL%201.1-blue.svg\" alt=\"License: BSL 1.1\" /></a>\n</p>\n\nMCP server that gives AI coding assistants (Claude Code, Cursor, Windsurf) the ability to **see and interact with mobile devices**. 49 tools for screenshots, UI inspection, touch interaction, AI-powered visual analysis, Flutter widget tree inspection, video recording, and test generation.\n\n> AI assistants can read your code but can't see your phone. This fixes that.\n\n## Why This One?\n\n| Feature | mobile-device-mcp | mobile-next/mobile-mcp | appium/appium-mcp |\n|---------|:-:|:-:|:-:|\n| Total tools | **49** | 20 | ~15 |\n| Setup | `npx` (30 sec) | `npx` | Requires Appium server |\n| AI visual analysis | **12 tools** (Claude + Gemini) | None | Vision-based finding |\n| Flutter widget tree | **10 tools** (Dart VM Service) | None | None |\n| Smart element finding | **4-tier** (<1ms local search) | Accessibility tree only | XPath/selectors |\n| Companion app (23x faster UI tree) | Yes | No | No |\n| Video recording | Yes | No | No |\n| Test script generation | **TS, Python, JSON** | No | Java/TestNG only |\n| iOS simulator support | Yes | Yes | Yes |\n| iOS real device | Planned | Yes | Yes |\n| Screenshot compression | **89%** (251KB->28KB) | None | 50-80% |\n| Multi-provider AI | Claude + Gemini | N/A | Single provider |\n| Price | Free + Pro (₹499/mo) | Free | Free |\n\n## The Problem\n\nWeb developers have browser DevTools, Playwright, and Puppeteer -- AI assistants can click around, take screenshots, and verify fixes. Mobile developers? They're stuck manually screenshotting, copying logs, and describing what's on screen. They're **human middleware** between the AI and the device.\n\n## What This Does\n\n```\nDeveloper: \"The login button doesn't work\"\n\nWithout this tool:                    With this tool:\n  1. Manually screenshot              1. AI calls take_screenshot -> sees the screen\n  2. Paste into AI chat               2. AI calls smart_tap(\"login button\") -> taps it\n  3. AI guesses what's wrong          3. AI calls verify_screen(\"error message shown\") -> sees result\n  4. Apply fix, rebuild               4. AI calls visual_diff -> confirms fix worked\n  5. Repeat 4-5 times                 5. Done.\n```\n\n## Quick Start\n\n### Install\n\n```bash\nnpx mobile-device-mcp\n```\n\nNo global install needed. Runs directly via npx.\n\n### Prerequisites\n- Node.js 18+\n- Android device/emulator connected via ADB\n- ADB installed ([Android SDK Platform Tools](https://developer.android.com/tools/releases/platform-tools))\n\n### Setup (One-time, 30 seconds)\n\n1. **Get a Google AI key** (free tier available): [aistudio.google.com/apikey](https://aistudio.google.com/apikey)\n\n2. **Add `.mcp.json` to your project root:**\n\n**macOS / Linux:**\n```json\n{\n  \"mcpServers\": {\n    \"mobile-device\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mobile-device-mcp\"],\n      \"env\": {\n        \"GOOGLE_API_KEY\": \"your-google-api-key\"\n      }\n    }\n  }\n}\n```\n\n**Windows:**\n```json\n{\n  \"mcpServers\": {\n    \"mobile-device\": {\n      \"type\": \"stdio\",\n      \"command\": \"cmd\",\n      \"args\": [\"/c\", \"npx\", \"-y\", \"mobile-device-mcp\"],\n      \"env\": {\n        \"GOOGLE_API_KEY\": \"your-google-api-key\"\n      }\n    }\n  }\n}\n```\n\n**With Pro license key** (after [purchasing Pro](https://rzp.io/rzp/r4ijQsJY)):\n\n<details>\n<summary>macOS / Linux (Pro)</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"mobile-device\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mobile-device-mcp\"],\n      \"env\": {\n        \"GOOGLE_API_KEY\": \"your-google-api-key\",\n        \"MOBILE_MCP_LICENSE_KEY\": \"MDMCP-XXXXX-XXXXX-XXXXX-XXXXX\"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary>Windows (Pro)</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"mobile-device\": {\n      \"type\": \"stdio\",\n      \"command\": \"cmd\",\n      \"args\": [\"/c\", \"npx\", \"-y\", \"mobile-device-mcp\"],\n      \"env\": {\n        \"GOOGLE_API_KEY\": \"your-google-api-key\",\n        \"MOBILE_MCP_LICENSE_KEY\": \"MDMCP-XXXXX-XXXXX-XXXXX-XXXXX\"\n      }\n    }\n  }\n}\n```\n</details>\n\n3. **Open your AI coding assistant** from that directory. That's it.\n\nThe server starts and stops automatically -- you never run it manually. Your AI assistant manages it as a background process via the MCP protocol.\n\n### Verify It Works\n\n**Claude Code:** type `/mcp` -- you should see `mobile-device: Connected`\n\n**Cursor:** check MCP panel in settings\n\nThen just talk to your phone:\n\n```\nYou: \"Open my app, tap the login button, type test@email.com in the email field\"\nAI:  [takes screenshot -> sees the screen -> smart_tap(\"login button\") -> smart_type(\"email field\", \"test@email.com\")]\n\nYou: \"Find all the bugs on this screen\"\nAI:  [analyze_screen -> inspects layout, checks for overflow, missing labels, broken states]\n\nYou: \"Navigate to settings and verify dark mode works\"\nAI:  [smart_tap(\"settings\") -> take_screenshot -> smart_tap(\"dark mode toggle\") -> visual_diff -> reports result]\n```\n\nNo test scripts. No manual screenshots. Just describe what you want in plain English.\n\n### Works with Any AI Coding Assistant\n\n| Tool | Config file | Docs |\n|------|------------|------|\n| **Claude Code** | `.mcp.json` in project root | [claude.ai/docs](https://claude.ai/docs) |\n| **Cursor** | `.cursor/mcp.json` | [cursor.com/docs](https://cursor.com/docs) |\n| **VS Code + Copilot** | MCP settings | [code.visualstudio.com](https://code.visualstudio.com) |\n| **Windsurf** | MCP settings | [windsurf.com](https://windsurf.com) |\n\nAll use the same JSON config -- just put it in the right file for your editor.\n\n### Drop Into Any Project\n\nCopy `.mcp.json` into any mobile project -- Flutter, React Native, Kotlin, Swift -- and your AI assistant gets device superpowers in that directory. No global install needed.\n\n## Free vs Pro\n\n<a name=\"pro\"></a>\n\n### Free (14 tools) -- no license key needed\n\n| Tool | What it does |\n|------|-------------|\n| `list_devices` | List all connected Android devices/emulators |\n| `get_device_info` | Model, manufacturer, Android version, SDK level |\n| `get_screen_size` | Screen resolution in pixels |\n| `take_screenshot` | Capture screenshot (PNG or JPEG, configurable quality & resize) |\n| `get_ui_elements` | Get the accessibility/UI element tree as structured JSON |\n| `tap` | Tap at coordinates |\n| `double_tap` | Double tap at coordinates |\n| `long_press` | Long press at coordinates |\n| `swipe` | Swipe between two points |\n| `type_text` | Type text into the focused field |\n| `press_key` | Press a key (home, back, enter, volume, etc.) |\n| `list_apps` | List installed apps |\n| `get_current_app` | Get the foreground app |\n| `get_logs` | Get logcat entries with filtering |\n\n### Pro (35 additional tools) -- [₹499/mo](https://rzp.io/rzp/r4ijQsJY)\n\n**[Get Pro License](https://rzp.io/rzp/r4ijQsJY)** -- unlock all 49 tools. After payment, you'll receive your license key via email within 1 hour. Add it to your `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mobile-device\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mobile-device-mcp\"],\n      \"env\": {\n        \"GOOGLE_API_KEY\": \"your-google-api-key\",\n        \"MOBILE_MCP_LICENSE_KEY\": \"your-license-key\"\n      }\n    }\n  }\n}\n```\n\n#### AI Visual Analysis (12 tools)\n\nUse AI vision (Claude or Gemini) to understand what's on screen.\n\n| Tool | What it does |\n|------|-------------|\n| `analyze_screen` | AI describes the screen: app name, screen type, interactive elements, visible text, suggestions |\n| `find_element` | Find a UI element by description: *\"the login button\"*, *\"email input field\"* |\n| `smart_tap` | Find an element by description and tap it in one step |\n| `smart_type` | Find an input field by description, focus it, and type text |\n| `suggest_actions` | Plan actions to achieve a goal: *\"log into the app\"*, *\"add item to cart\"* |\n| `visual_diff` | Compare current screen with a previous screenshot -- what changed? |\n| `extract_text` | Extract all visible text from the screen (AI-powered OCR) |\n| `verify_screen` | Verify an assertion: *\"the login was successful\"*, *\"error message is showing\"* |\n| `wait_for_settle` | Wait until the screen stops changing |\n| `wait_for_element` | Wait for a specific element to appear on screen |\n| `handle_popup` | Detect and dismiss popups, dialogs, permission prompts |\n| `fill_form` | Fill multiple form fields in one step |\n\n#### Flutter Widget Tree (10 tools)\n\nConnect to running Flutter apps via Dart VM Service Protocol. Maps every widget to its source code location (`file:line`).\n\n| Tool | What it does |\n|------|-------------|\n| `flutter_connect` | Discover and connect to a running Flutter app on the device |\n| `flutter_disconnect` | Disconnect from the Flutter app and clean up resources |\n| `flutter_get_widget_tree` | Get the full widget tree (summary or detailed) |\n| `flutter_get_widget_details` | Get detailed properties of a specific widget by ID |\n| `flutter_find_widget` | Search the widget tree by type, text, or description |\n| `flutter_get_source_map` | Map every widget to its source code location (file:line:column) |\n| `flutter_screenshot_widget` | Screenshot a specific widget in isolation |\n| `flutter_debug_paint` | Toggle debug paint overlay (shows widget boundaries & padding) |\n| `flutter_hot_reload` | Hot reload Flutter app (preserves state) |\n| `flutter_hot_restart` | Hot restart Flutter app (resets state) |\n\n#### iOS Simulator (4 tools)\n\nmacOS only. Control iOS simulators via `xcrun simctl`.\n\n| Tool | What it does |\n|------|-------------|\n| `ios_list_simulators` | List available iOS simulators |\n| `ios_boot_simulator` | Boot a simulator by name or UDID |\n| `ios_shutdown_simulator` | Shut down a running simulator |\n| `ios_screenshot` | Take a screenshot of a simulator |\n\n#### Video Recording (2 tools)\n\n| Tool | What it does |\n|------|-------------|\n| `record_screen` | Start recording the device screen |\n| `stop_recording` | Stop recording and save the video |\n\n#### Test Generation (3 tools)\n\n| Tool | What it does |\n|------|-------------|\n| `start_test_recording` | Start recording your MCP tool calls |\n| `stop_test_recording` | Stop recording and generate a test script |\n| `get_recorded_actions` | Get recorded actions as TypeScript, Python, or JSON |\n\n#### App Management (4 tools)\n\n| Tool | What it does |\n|------|-------------|\n| `launch_app` | Launch an app by package name |\n| `stop_app` | Force stop an app |\n| `install_app` | Install an APK |\n| `uninstall_app` | Uninstall an app |\n\n## Performance\n\nThe server is optimized to minimize latency and AI token costs:\n\n- **4-tier element search**: companion app (instant) -> local text match (<1ms) -> cached AI -> fresh AI. `smart_tap` is **35x faster** than naive AI calls (205ms vs 7.6s).\n- **Companion app**: AccessibilityService-based Android app provides UI tree in 105ms (23x faster than UIAutomator's 2448ms). Auto-installs on first use.\n- **Screenshot compression**: AI tools auto-compress to JPEG q=60, 400w -- **89% smaller** (251KB -> 28KB) with zero AI quality loss.\n- **Parallel capture**: Screenshot + UI tree fetched simultaneously via `Promise.all()`.\n- **TTL caching**: 5-second cache avoids redundant ADB calls for rapid-fire tool usage.\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `GOOGLE_API_KEY` or `GEMINI_API_KEY` | Google API key for Gemini vision (recommended) | -- |\n| `ANTHROPIC_API_KEY` | Anthropic API key for Claude vision | -- |\n| `MOBILE_MCP_LICENSE_KEY` | License key to unlock Pro tools | -- |\n| `MCP_AI_PROVIDER` | Force AI provider: `\"anthropic\"` or `\"google\"` | Auto-detected |\n| `MCP_AI_MODEL` | Override AI model | `gemini-2.5-flash` / `claude-sonnet-4-20250514` |\n| `MCP_ADB_PATH` | Custom ADB binary path | Auto-discovered |\n| `MCP_DEFAULT_DEVICE` | Default device serial | Auto-discovered |\n| `MCP_SCREENSHOT_FORMAT` | `\"png\"` or `\"jpeg\"` | `jpeg` |\n| `MCP_SCREENSHOT_QUALITY` | JPEG quality (1-100) | `80` |\n| `MCP_SCREENSHOT_MAX_WIDTH` | Resize screenshots to this max width | `720` |\n\n## Architecture\n\n```\nsrc/\n|-- index.ts              # CLI entry point (auto-discovery, env config)\n|-- server.ts             # MCP server factory\n|-- license.ts            # License validation and tier gating\n|-- types.ts              # Shared interfaces\n|-- drivers/android/      # ADB driver (DeviceDriver implementation)\n|   |-- adb.ts            # Low-level ADB command wrapper\n|   |-- companion-client.ts # TCP client for companion app\n|   +-- index.ts          # AndroidDriver class (4-strategy UI element retrieval)\n|-- drivers/flutter/      # Dart VM Service driver\n|   |-- index.ts          # FlutterDriver (discovery, inspection, source mapping, hot reload)\n|   +-- vm-service.ts     # JSON-RPC 2.0 WebSocket client (DDS redirect handling)\n|-- drivers/ios/          # iOS Simulator driver (macOS only)\n|   |-- index.ts          # IOSSimulatorDriver via xcrun simctl\n|   +-- simctl.ts         # Low-level simctl command wrapper\n|-- tools/                # MCP tool registrations (free + pro gating)\n|   |-- device-tools.ts   # Device management\n|   |-- screen-tools.ts   # Screenshots & UI inspection\n|   |-- interaction-tools.ts # Touch, type, keys\n|   |-- app-tools.ts      # App management\n|   |-- log-tools.ts      # Logcat\n|   |-- ai-tools.ts       # AI-powered tools\n|   |-- flutter-tools.ts  # Flutter widget inspection\n|   |-- ios-tools.ts      # iOS simulator tools\n|   |-- video-tools.ts    # Screen recording\n|   +-- recording-tools.ts # Test generation\n|-- recording/            # Test script generation\n|   |-- recorder.ts       # ActionRecorder (records MCP tool calls)\n|   +-- generator.ts      # TestGenerator (TypeScript/Python/JSON output)\n|-- ai/                   # AI visual analysis engine\n|   |-- client.ts         # Multi-provider client (Anthropic + Google)\n|   |-- prompts.ts        # System prompts & UI element summarizer\n|   |-- analyzer.ts       # ScreenAnalyzer orchestrator (caching, parallel capture)\n|   +-- element-search.ts # Local element search (text/alias matching, no AI needed)\n+-- utils/\n    |-- discovery.ts      # ADB auto-discovery\n    +-- image.ts          # PNG parsing, JPEG compression, bilinear resize\n\ncompanion-app/            # Android companion app (Kotlin)\n                          # AccessibilityService + TCP JSON-RPC for fast UI tree\n```\n\n## Roadmap\n\n- [ ] iOS physical device support\n- [ ] Multi-device orchestration\n- [ ] CI/CD integration\n- [ ] Cloud device farm support\n\n## Tested On\n\n- **Devices**: Pixel 8 (Android 16), Samsung Galaxy series, Android emulators\n- **Apps**: Telegram, Instagram, Spotify, WhatsApp, YouTube, Chrome, Settings, and Flutter apps\n- **AI Providers**: Google Gemini 2.5 Flash, Anthropic Claude\n- **Platforms**: Windows 11, macOS (iOS simulators)\n- **Connection**: USB and wireless ADB\n\n## License\n\n[Business Source License 1.1](LICENSE)\n\n- **Free for individuals and non-commercial use**\n- **Commercial use requires a paid license**\n- Converts to Apache 2.0 on March 23, 2030\n\nSee [LICENSE](LICENSE) for full terms.\n",
  "bytes": 15650,
  "sha": "f00b352c034e90b2e21f9d8ee3cb9538e5a21cba829bd85045bd38ea9694d1e6",
  "repo_slug": "saranshbamania/mobile-device-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_saranshbamania_mobile_device_m_4812d2e4/readme"
}