Skip to content
Back to search

android-mcp-server

An MCP server that provides control over Android devices via adb

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/minhalvp--android-mcp-server/badge.svg)](/listings/minhalvp--android-mcp-server)

HTML

<a href="/listings/minhalvp--android-mcp-server"><img src="/api/listings/minhalvp--android-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Clone the repository:

git clone https://github.com/minhalvp/android-mcp-server.git
cd android-mcp-server

2. Install dependencies: This project uses [uv](https://github.com/astral-sh/uv) for project management via various methods of [installation](https://docs.astral.sh/uv/getting-started/installation/).

uv python install 3.11
uv sync

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 215 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Android MCP Server
  2. An MCP (Model Context Protocol) server that provides programmatic control over
  3. Android devices through ADB (Android Debug Bridge). This server exposes
  4. various Android device management capabilities that can be accessed by MCP
  5. clients like [Claude desktop](https://modelcontextprotocol.io/quickstart/user)
  6. and Code editors
  7. (e.g. [Cursor](https://docs.cursor.com/context/model-context-protocol))
  8. ## Features
  9. - 🔧 ADB Command Execution
  10. - 📸 Device Screenshot Capture
  11. - 🎯 UI Layout Analysis
  12. - 📱 Device Package Management
  13. ## Prerequisites
  14. - Python 3.x
  15. - ADB (Android Debug Bridge) installed and configured
  16. - Android device or emulator (not tested)
  17. ## Installation
  18. 1. Clone the repository:
  19. ```bash
  20. git clone https://github.com/minhalvp/android-mcp-server.git
  21. cd android-mcp-server
  22. ```
  23. 2. Install dependencies:
  24. This project uses [uv](https://github.com/astral-sh/uv) for project
  25. management via various methods of
  26. [installation](https://docs.astral.sh/uv/getting-started/installation/).
  27. ```bash
  28. uv python install 3.11
  29. uv sync
  30. ```
  31. ## Configuration
  32. The server supports flexible device configuration with multiple usage scenarios.
  33. ### Device Selection Modes
  34. **1. Automatic Selection (Recommended for single device)**
  35. - No configuration file needed
  36. - Automatically connects to the only connected device
  37. - Perfect for development with a single test device
  38. **2. Manual Device Selection**
  39. - Use when you have multiple devices connected
  40. - Specify exact device in configuration file
  41. ### Configuration File (Optional)
  42. The configuration file (`config.yaml`) is **optional**. If not present, the server will automatically select the device if only one is connected.
  43. #### For Automatic Selection
  44. Simply ensure only one device is connected and run the server - no configuration needed!
  45. #### For Manual Selection
  46. 1. Create a configuration file:
  47. ```bash
  48. cp config.yaml.example config.yaml
  49. ```
  50. 2. Edit `config.yaml` and specify your device:
  51. ```yaml
  52. device:
  53. name: "your-device-serial-here" # Device identifier from 'adb devices'
  54. ```
  55. **For auto-selection**, you can use any of these methods:
  56. ```yaml
  57. device:
  58. name: null # Explicit null (recommended)
  59. # name: "" # Empty string
  60. # name: # Or leave empty/comment out
  61. ```
  62. ### Finding Your Device Serial
  63. To find your device identifier, run:
  64. ```bash
  65. adb devices
  66. ```
  67. Example output:
  68. ```
  69. List of devices attached
  70. 13b22d7f device
  71. emulator-5554 device
  72. ```
  73. Use the first column value (e.g., `13b22d7f` or `emulator-5554`) as the device name.
  74. ### Usage Scenarios
  75. | Scenario | Configuration Required | Behavior |
  76. |----------|----------------------|----------|
  77. | Single device connected | None | ✅ Auto-connects to the device |
  78. | Multiple devices, want specific one | `config.yaml` with `device.name` | ✅ Connects to specified device |
  79. | Multiple devices, no config | None | ❌ Shows error with available devices |
  80. | No devices connected | N/A | ❌ Shows "no devices" error |
  81. **Note**: If you have multiple devices connected and don't specify which one to use, the server will show an error message listing all available devices.
  82. ## Usage
  83. An MCP client is needed to use this server. The Claude Desktop app is an example
  84. of an MCP client. To use this server with Claude Desktop:
  85. 1. Locate your Claude Desktop configuration file:
  86. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  87. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  88. 2. Add the Android MCP server configuration to the `mcpServers` section:
  89. ```json
  90. {
  91. "mcpServers": {
  92. "android": {
  93. "command": "path/to/uv",
  94. "args": ["--directory", "path/to/android-mcp-server", "run", "server.py"]
  95. }
  96. }
  97. }
  98. ```
  99. Replace:
  100. - `path/to/uv` with the actual path to your `uv` executable
  101. - `path/to/android-mcp-server` with the absolute path to where you cloned this
  102. repository
  103. <https://github.com/user-attachments/assets/c45bbc17-f698-43e7-85b4-f1b39b8326a8>
  104. ### Available Tools
  105. The server exposes the following tools:
  106. ```python
  107. def get_packages() -> str:
  108. """
  109. Get all installed packages on the device.
  110. Returns:
  111. str: A list of all installed packages on the device as a string
  112. """
  113. ```
  114. ```python
  115. def execute_adb_command(command: str) -> str:
  116. """
  117. Executes an ADB command and returns the output.
  118. Args:
  119. command (str): The ADB command to execute
  120. Returns:
  121. str: The output of the ADB command
  122. """
  123. ```
  124. ```python
  125. def get_uilayout() -> str:
  126. """
  127. Retrieves information about clickable elements in the current UI.
  128. Returns a formatted string containing details about each clickable element,
  129. including their text, content description, bounds, and center coordinates.
  130. Returns:
  131. str: A formatted list of clickable elements with their properties
  132. """
  133. ```
  134. ```python
  135. def get_screenshot() -> Image:
  136. """
  137. Takes a screenshot of the device and returns it.
  138. Returns:
  139. Image: the screenshot
  140. """
  141. ```
  142. ```python
  143. def get_package_action_intents(package_name: str) -> list[str]:
  144. """
  145. Get all non-data actions from Activity Resolver Table for a package
  146. Args:
  147. package_name (str): The name of the package to get actions for
  148. Returns:
  149. list[str]: A list of all non-data actions from the Activity Resolver
  150. Table for the package
  151. """
  152. ```
  153. ## Contributing
  154. Contributions are welcome!
  155. ## Acknowledgments
  156. - Built with
  157. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.