{
  "markdown": "# Android MCP Server\n\n[![npm version](https://img.shields.io/npm/v/android-mcp-server)](https://www.npmjs.com/package/android-mcp-server)\n[![npm downloads](https://img.shields.io/npm/dw/android-mcp-server)](https://www.npmjs.com/package/android-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![android-mcp-server MCP server](https://glama.ai/mcp/servers/martingeidobler/android-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/martingeidobler/android-mcp-server)\n[![Awesome MCP Servers](https://img.shields.io/badge/Awesome-MCP%20Servers-fc60a8)](https://github.com/punkpeye/awesome-mcp-servers)\n[![Socket                                                                                                              \n  Badge](https://socket.dev/api/badge/npm/package/android-mcp-server)](https://socket.dev/npm/package/android-mcp-server)\n\nMCP server for controlling Android emulators and devices via ADB. Gives AI assistants the ability to see, interact with, and debug Android apps — taking screenshots, tapping elements, reading logs, and documenting bugs.\n\n[npm Package](https://www.npmjs.com/package/android-mcp-server) | [GitHub](https://github.com/martingeidobler/android-mcp-server) | [Issues](https://github.com/martingeidobler/android-mcp-server/issues)\n\n![ezgif-3bbb68e918812643](https://github.com/user-attachments/assets/d78ef5ac-c401-4249-9776-4eda86cd4020)\n^ Sped up for better viewing. [More demos and test cases](DEMOS.md).\n\n## Features\n\n- **25 tools** for complete Android device control\n- **Screenshot capture** with intelligent compression (Sharp-based, max 1280px)\n- **UI tree inspection** — read element hierarchy with bounds, text, resource IDs, and state\n- **Touch automation** — tap, swipe, scroll, type text, press hardware keys\n- **Element targeting** — find and tap elements by resource-id, text, or content-desc\n- **App lifecycle** — install APKs, launch apps, inspect current activity\n- **Logcat integration** — filter by package, log level, or timestamp\n- **Device management** — list devices, start emulators, get device info\n- **Compound actions** — `tap_and_wait` combines tap + settle + UI tree in one round trip\n- **Persistent ADB shell** — reuses a single shell session for faster command execution\n- **Device info caching** — queries device properties once per session\n- **Multi-device support** — target specific devices by ID\n- **Zero app modifications** — works with any Android app via ADB, no SDK integration needed\n\n## Prerequisites\n\n- Node.js 18+\n- Android SDK with platform-tools (ADB) and emulator\n- A running Android emulator or connected device\n\n### Finding your ANDROID_HOME\n\nThe server auto-discovers the SDK at `~/Library/Android/sdk` (macOS) or via `ANDROID_HOME`. If your SDK is elsewhere, set `ANDROID_HOME` in the MCP config (see below).\n\nTo check:\n```bash\n# macOS\nls ~/Library/Android/sdk/platform-tools/adb\n\n# Or find it via Android Studio: Settings > Languages & Frameworks > Android SDK\n```\n\n## Setup\n\n<details>\n<summary><b>Claude Code</b></summary>\n\n```bash\nclaude mcp add --scope user android -- npx -y android-mcp-server\n```\n\nThis registers the server globally so it's available in all projects. Use `--scope project` instead to limit it to the current project.\n\nIf your SDK is not in the default location:\n```bash\nclaude mcp add --scope user --env ANDROID_HOME=/path/to/sdk android -- npx -y android-mcp-server\n```\n\n</details>\n\n<details>\n<summary><b>Claude Desktop</b></summary>\n\nAdd to your Claude Desktop config file:\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"android\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"android-mcp-server\"],\n      \"env\": {\n        \"ANDROID_HOME\": \"/path/to/android/sdk\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>VS Code</b></summary>\n\nAdd to your VS Code settings (`.vscode/settings.json`):\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"android\": {\n        \"command\": \"npx\",\n        \"args\": [\"-y\", \"android-mcp-server\"],\n        \"env\": {\n          \"ANDROID_HOME\": \"/path/to/android/sdk\"\n        }\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Cursor</b></summary>\n\nAdd to your Cursor MCP config (`~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"android\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"android-mcp-server\"],\n      \"env\": {\n        \"ANDROID_HOME\": \"/path/to/android/sdk\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Windsurf</b></summary>\n\nAdd to your Windsurf MCP config (`~/.codeium/windsurf/mcp_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"android\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"android-mcp-server\"],\n      \"env\": {\n        \"ANDROID_HOME\": \"/path/to/android/sdk\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Project config (.mcp.json)</b></summary>\n\nAdd to your project's `.mcp.json` (checked into version control so your team gets it too):\n\n```json\n{\n  \"mcpServers\": {\n    \"android\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"android-mcp-server\"],\n      \"env\": {\n        \"ANDROID_HOME\": \"/path/to/android/sdk\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Build from source</b></summary>\n\n```bash\ngit clone https://github.com/martingeidobler/android-mcp-server.git\ncd android-mcp-server\nnpm install\nnpm run build\nclaude mcp add --scope user android -- node /path/to/android-mcp-server/dist/index.js\n```\n\n</details>\n\n## Available Tools\n\n### Device Management\n| Tool | Description |\n|------|-------------|\n| `list_devices` | List connected Android devices and emulators |\n| `list_avds` | List available Android Virtual Devices |\n| `start_emulator` | Start an AVD by name (waits up to 60s) |\n\n### Screenshot & UI Analysis\n| Tool | Description |\n|------|-------------|\n| `screenshot` | Take screenshot for visual analysis. Optional `save_path` to save to disk |\n| `get_ui_tree` | Get UI element hierarchy with bounds, text, resource IDs, and state |\n\n### Interaction\n| Tool | Description |\n|------|-------------|\n| `tap` | Tap at screen coordinates |\n| `tap_element` | Tap element by resource-id, text, or content-desc |\n| `tap_and_wait` | Tap element, wait for UI to settle, return new UI tree — single round trip |\n| `long_press` | Long press at coordinates (context menus, drag handles) |\n| `double_tap` | Double tap at coordinates |\n| `multi_tap` | Tap the same coordinates N times with a fixed interval (spam tapping) |\n| `tap_sequence` | Multi-step action chain: taps, waits, text input, key presses, swipes in any order |\n| `type_text` | Type text into focused input |\n| `press_key` | Press key (back, home, enter, tab, delete, menu, etc.) |\n| `swipe` | Swipe gesture between coordinates |\n| `scroll_to_element` | Scroll until element is visible |\n| `wait_for_element` | Wait for element to appear (with timeout) |\n\n### Diagnostics\n| Tool | Description |\n|------|-------------|\n| `get_logs` | Get logcat output, filterable by package, log level, and time |\n| `clear_logs` | Clear logcat buffer (call before reproducing a bug for clean output) |\n| `get_device_info` | Get model, Android version, API level, screen size, DPI |\n\n### App Management\n| Tool | Description |\n|------|-------------|\n| `launch_app` | Launch app by package name |\n| `install_apk` | Install APK file |\n| `get_current_activity` | Get foreground app and activity |\n| `pull_file` | Pull a file from the device to local filesystem |\n| `adb_shell` | Run arbitrary ADB shell command |\n\n## Example Workflows\n\n### Bug documentation\n\n<!-- TODO: Add GIF demo -->\n\n> \"Clear the logs, open the settings screen, tap the save button, then show me the logs and a screenshot\"\n\nClaude will: `clear_logs` → `launch_app` → `tap_element` → `get_logs(package_name=\"com.example.app\", level=\"E\")` → `screenshot(save_path=\"./bugs/settings-crash.png\")`\n\n### UI testing\n\n<!-- TODO: Add GIF demo -->\n\n> \"Navigate through the login flow and verify each screen matches the designs\"\n\nClaude will use `screenshot` + `get_ui_tree` to see and understand each screen, `tap_element`/`type_text` to interact, and its vision capabilities to compare against mockups or descriptions.\n\n### Smoke testing\n\n<!-- TODO: Add GIF demo -->\n\n> \"Install the APK, launch the app, and tap through the main screens to check nothing crashes\"\n\nClaude will: `install_apk` → `launch_app` → navigate with `tap_element` → `get_logs(level=\"E\")` to check for errors after each screen.\n\n### Element interaction\n\n<!-- TODO: Add GIF demo -->\n\n> \"Open Settings, search for 'display', tap the first result, then go back\"\n\nClaude will: `launch_app(package_name=\"com.android.settings\")` → `tap_and_wait(by=\"text\", value=\"Search settings\")` → `type_text(\"display\")` → `tap_and_wait(by=\"text\", value=\"Display\")` → `press_key(key=\"back\")`\n\n## Demos & Prompting Guide\n\n- **[DEMOS.md](DEMOS.md)** — copy-paste prompt scenarios you can try right now\n- **[PROMPTING.md](PROMPTING.md)** — best practices, performance tips, and common pitfalls\n\n## How It Works\n\nThe server communicates over stdio using the [Model Context Protocol](https://modelcontextprotocol.io). All device interaction goes through ADB — no modifications to your app are required. Screenshots are captured in memory, compressed, and returned as base64 images that the AI can see and analyze visually.\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT - see [LICENSE](LICENSE).\n",
  "bytes": 9553,
  "sha": "c731b6cd2de926d7d496feb8aec7a436ac62e024a46b72012b641a1e04769bf4",
  "repo_slug": "martingeidobler/android-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_martingeidobler_android_5d0e478c/readme"
}