Provides tools for controlling Android devices over ADB, including reading logcat, clearing logs, inspecting the current UI hierarchy, listing installed packages, and running safe allowlisted shell commands.
Android ADB MCP Server is a Model Context Protocol (MCP) server that lets AI assistants — such as Claude and OpenCode, or VS Code through its Copilot/agent integration — control Android devices over ADB securely. It exposes tools to read logcat, inspect the current UI hierarchy, list installed packages, and run restricted shell commands, all gated by an allowlist that mitigates arbitrary command execution.
A note on terminology: Claude and OpenCode are AI assistants. VS Code is not an AI — it is a code editor that hosts AI assistants (GitHub Copilot, and MCP-capable extensions) and is itself an MCP client. The server works with any MCP-capable client.
Node.js v18+ (tested up to Node.js 26).
ADB installed and reachable via the system PATH (adb version must work), or located via ADB_PATH / ANDROID_HOME / standard SDK paths.
USB debugging enabled on the Android device (Developer options → USB debugging).
git clone https://github.com/Neem2004/android-mcp-server.git
cd android-mcp-server
npm installnpm run buildThis produces the compiled code in the dist/ folder.
⚠️ Important:
dist/is generated locally and is not committed to the repository. You must runnpm run buildbefore configuring your MCP client, or the server will fail to start.
💡 Quick start (published on npm): you can skip the clone and build entirely — the server is published as
@neem2004/android-mcp-serverand includes the compileddist/. Run it directly withnpx -y @neem2004/android-mcp-server, as shown in the configs below. The absolute path form targets a local clone (replaceYOUR_PATH_TOwith its location).
Each MCP client keeps its servers in a different file, with a different format. Below are the three most common setups, each with the published-package form (npx) and the local-clone alternative.
File: opencode.json at your project root, or ~/.config/opencode/opencode.json (global).
{
"mcp": {
"android": {
"type": "local",
"command": ["npx", "-y", "@neem2004/android-mcp-server"],
"enabled": true
}
}
}Local clone alternative — "command": ["node", "YOUR_PATH_TO/android-mcp-server/dist/index.js"].
File: %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).
{
"mcpServers": {
"android": {
"command": "npx",
"args": ["-y", "@neem2004/android-mcp-server"]
}
}
}Local clone alternative — "command": "node" with "args": ["YOUR_PATH_TO/android-mcp-server/dist/index.js"].
File: .vscode/mcp.json in your workspace (or via the MCP: Open User Configuration command). VS Code uses servers as the top-level key (not mcpServers).
{
"servers": {
"android": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@neem2004/android-mcp-server"]
}
}
}Local clone alternative — "command": "node" with "args": ["YOUR_PATH_TO/android-mcp-server/dist/index.js"].
Development note: instead of the compiled build you can run TypeScript directly via
tsxby replacing the argument withsrc/index.tsand usingnpx tsxas the command. Prefer the compiled build for reliability.
npm test # runs the unit test suite
npm run build # compiles TypeScript to dist/
npm run dev # runs the server directly via tsx (development)Tool | Description | Arguments |
| Dumps the |
|
| Clears the device log buffer | — |
| Returns the current UI hierarchy (XML/text) | — |
| Lists installed packages |
|
| Runs a safe allowlisted shell command |
|
This server prioritizes safety over arbitrary command execution:
Shell allowlist: adb_execute_shell only accepts commands whose prefix is authorized (getprop, dumpsys, pm list). Anything else is rejected with a descriptive error. Command chaining (&&, ||, ;, |) and injection metacharacters are also blocked.
No root: no superuser privileges are requested; it works on standard ADB APIs.
Commands run via execFile (no intermediate shell), avoiding metacharacter injection.
The logic lives in
src/adb/security.ts; review it before broadening permissions.
If you do not have ADB yet:
Windows: download the official platform-tools and add its folder to your system PATH.
macOS / Linux: install via your package manager (e.g. brew install android-platform-tools, apt install adb).
Verify with:
adb devicesYour device should appear as device (not unauthorized/offline). The server will use ADB_PATH, then ANDROID_HOME/ANDROID_SDK_ROOT, then standard SDK locations, before falling back to adb on the PATH.
This project is 100% open source and independently maintained. If Android ADB MCP Server saves your team time or improves your automation workflows, please consider supporting its continued development.
🔗 GitHub Sponsors: Sponsor Neem2004
💼 Companies: corporate sponsorship funds new tools, security hardening, and priority support.
Every contribution, however small, helps keep the project active, documented, and secure. Thank you for your support!
ISC
Related MCP server: mobile-debug-mcp
Android ADB MCP Server es un servidor del Model Context Protocol (MCP) que permite a asistentes de IA —como Claude y OpenCode, o VS Code mediante su integración con Copilot/agente— controlar dispositivos Android vía ADB de forma segura. Expone herramientas para leer el logcat, inspeccionar la jerarquía de la UI, listar paquetes instalados y ejecutar comandos shell restringidos, todo a través de una lista blanca que mitiga los riesgos de ejecución arbitraria.
Nota sobre terminología: Claude y OpenCode son asistentes de IA. VS Code no es una IA — es un editor de código que aloja asistentes de IA (GitHub Copilot y extensiones con soporte MCP) y que además es un cliente MCP. El servidor funciona con cualquier cliente compatible con MCP.
Node.js v18+ (probado hasta Node.js 26).
ADB instalado y accesible en el PATH del sistema (adb version debe funcionar), o localizado vía ADB_PATH / ANDROID_HOME / rutas estándar del SDK.
Depuración USB activada en el dispositivo Android (Opciones de desarrollador → Depuración USB).
git clone https://github.com/Neem2004/android-mcp-server.git
cd android-mcp-server
npm installnpm run buildEsto genera el código compilado en la carpeta dist/.
⚠️ Importante:
dist/se genera localmente y no se sube al repositorio. Debes ejecutarnpm run buildantes de configurar tu cliente MCP, o el servidor no arrancará.
💡 Inicio rápido (publicado en npm): puedes saltarte el clonado y la compilación — el servidor está publicado como
@neem2004/android-mcp-servere incluye eldist/compilado. Ejecútalo directamente connpx -y @neem2004/android-mcp-server, como muestran las configuraciones de abajo. La forma de ruta absoluta apunta a un clon local (reemplazaTU_RUTApor su ubicación).
Cada cliente MCP guarda sus servidores en un archivo distinto, con un formato propio. A continuación están las tres configuraciones más comunes, cada una con la forma de paquete publicado (npx) y la alternativa de clon local.
Archivo: opencode.json en la raíz de tu proyecto, o ~/.config/opencode/opencode.json (global).
{
"mcp": {
"android": {
"type": "local",
"command": ["npx", "-y", "@neem2004/android-mcp-server"],
"enabled": true
}
}
}Alternativa de clon local — "command": ["node", "TU_RUTA/android-mcp-server/dist/index.js"].
Archivo: %APPDATA%\Claude\claude_desktop_config.json (Windows) o ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).
{
"mcpServers": {
"android": {
"command": "npx",
"args": ["-y", "@neem2004/android-mcp-server"]
}
}
}Alternativa de clon local — "command": "node" con "args": ["TU_RUTA/android-mcp-server/dist/index.js"].
Archivo: .vscode/mcp.json en tu workspace (o mediante el comando MCP: Open User Configuration). VS Code usa servers como clave raíz (no mcpServers).
{
"servers": {
"android": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@neem2004/android-mcp-server"]
}
}
}Alternativa de clon local — "command": "node" con "args": ["TU_RUTA/android-mcp-server/dist/index.js"].
Nota de desarrollo: en lugar del build compilado puedes ejecutar TypeScript directamente con
tsxreemplazando el argumento porsrc/index.tsy usandonpx tsxcomo comando. Para máxima fiabilidad, prefiere el build compilado.
npm test # ejecuta la suite de tests unitarios
npm run build # compila TypeScript a dist/
npm run dev # ejecuta el servidor directamente con tsx (desarrollo)Tool | Descripción | Argumentos |
| Vuelca el buffer de |
|
| Limpia el buffer de logs del dispositivo | — |
| Devuelve la jerarquía de la UI actual (XML/texto) | — |
| Lista los paquetes instalados |
|
| Ejecuta un comando shell seguro (lista blanca) |
|
Este servidor prioriza la seguridad frente a la ejecución arbitraria de comandos:
Lista blanca de comandos shell: adb_execute_shell solo acepta comandos cuyo prefijo esté autorizado (getprop, dumpsys, pm list). Cualquier otra cosa se rechaza con un error descriptivo. También se bloquean encadenamientos (&&, ||, ;, |) y metacaracteres de inyección.
Sin root: no se solicitan privilegios de superusuario; se trabaja sobre las APIs estándar de ADB.
Los comandos se ejecutan mediante execFile (sin pasar por un shell intermedio), evitando la inyección de metacaracteres.
La lógica vive en
src/adb/security.ts; revísalo antes de ampliar los permisos.
Si aún no tienes ADB:
Windows: descarga los platform-tools oficiales y agrega su carpeta al PATH del sistema.
macOS / Linux: instala con tu gestor de paquetes (p. ej. brew install android-platform-tools, apt install adb).
Verifica con:
adb devicesTu dispositivo debe aparecer como device (no unauthorized/offline). El servidor usará ADB_PATH, luego ANDROID_HOME/ANDROID_SDK_ROOT, luego rutas estándar del SDK, antes de caer a adb en el PATH.
Este proyecto es 100% open source y se mantiene de forma independiente. Si Android ADB MCP Server ahorra tiempo a tu equipo o mejora tus flujos de automatización, considera apoyar su desarrollo continuo.
🔗 GitHub Sponsors: Patrocina a Neem2004
💼 Empresas: el patrocinio corporativo financia nuevas herramientas, mejoras de seguridad y soporte prioritario.
Toda contribución, por pequeña que sea, ayuda a mantener el proyecto activo, documentado y seguro. ¡Gracias por tu apoyo!
ISC
Limpia el buffer de logcat del dispositivo Android.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden. It accurately states that the logcat buffer is cleared, but it does not disclose side effects such as permanent loss of current logs or that the action has no output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear, front-loaded sentence with no unnecessary words. It fully communicates the tool's purpose in minimal space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter utility that simply clears a buffer, the description is complete enough for most usage. It could mention irreversibility or connected-device requirements, but this is a minor gap given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to document. A baseline of 4 is appropriate since the description does not need to compensate for any schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Limpia el buffer de logcat del dispositivo Android' (clears the logcat buffer). This distinguishes it from siblings like adb_get_logcat by its clear verb 'Limpia', though it does not explicitly name sibling distinctions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: the tool is for clearing the logcat buffer. However, the description does not explicitly state when to prefer this over adb_get_logcat or any preconditions such as needing a connected device.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Obtiene la jerarquía de la UI actual del dispositivo Android como texto/XML.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral transparency burden. It does disclose that the tool returns the current UI hierarchy as text/XML, but it omits read-only/safety implications, device connection requirements, and potential failure modes. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that concisely states the action, target, scope, and output format. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool, the description covers the essential outcome and output type. It could add caveats like device connectivity or large output size, but the current level is sufficient for basic selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema description coverage, so there are no parameter semantics for the description to add. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Obtiene') and resource ('jerarquía de la UI actual del dispositivo Android'), and specifies the output format as text/XML. This clearly distinguishes it from siblings that handle logcat, packages, or shell commands.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is implied: use this when you need the current UI hierarchy for UI inspection or automation. However, the description gives no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives or preconditions like a connected device.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ejecuta un comando shell seguro en el dispositivo Android a través de una lista blanca de comandos.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | Comando shell a ejecutar (solo comandos permitidos). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does disclose a key behavior: commands are restricted by a whitelist ('a través de una lista blanca de comandos'). However, it does not specify which commands are allowed, how invalid commands are handled, or what output/return behavior to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence that front-loads the action and object before the whitelist detail. It contains no filler or redundant phrases beyond the whitelist mention, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description must supply critical context. It does not enumerate the whitelisted commands, describe the expected output, or explain error behavior. Without knowing what commands are permitted, an agent may struggle to construct a valid invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage of the only parameter: command is described as the shell command to execute, with only permitted commands allowed. The description adds little beyond restating the whitelist concept, so it remains at the schema-dominated baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: it executes an Android shell command, and the whitelist qualifier adds precision. This distinguishes it from sibling tools like adb_get_logcat, adb_clear_logcat, adb_dump_hierarchy, and adb_list_packages, which target different concerns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the phrase 'comando shell' — the agent can infer this tool is for running shell commands rather than logcat, hierarchy, or package operations. However, the description does not explicitly mention alternatives, exclusions, or when to prefer a sibling tool, so guidance remains implicit rather than direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Obtiene el buffer de logcat del dispositivo Android, opcionalmente filtrado por tag, nivel de log y limitado a las últimas N líneas.
| Name | Required | Description | Default |
|---|---|---|---|
| lines | No | Número de últimas líneas a retornar. | |
| log_level | No | Nivel mínimo de log a incluir. | |
| filter_tag | No | Filtra entradas por tag (etiqueta de log). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the behavioral disclosure burden. It communicates a read-style retrieval operation and the filtering/limiting behavior, but it does not explicitly state that it is non-destructive, what the output format looks like, or whether a device connection is required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the core action first and all optional modifiers in one clear clause. There is no filler, redundancy, or unnecessary background.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-style logcat tool with three optional parameters and no output schema, the description gives enough context to select and invoke it. It is slightly light on output format and explicit alternative routing, but those gaps are minor for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description only restates the filtering dimensions (tag, log level, latest N lines) without adding defaults, formats, or constraints beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Obtiene') and a concrete resource ('buffer de logcat del dispositivo Android'), and mentions the optional filters. This makes it clearly distinct from siblings like adb_clear_logcat or adb_dump_hierarchy even without naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies logcat retrieval ('obtiene el buffer de logcat'), so an agent can infer when to use it. However, it does not provide explicit guidance about when not to use it or how it compares to alternatives such as adb_clear_logcat.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista los paquetes instalados del dispositivo Android, con filtro por nombre y opción de incluir paquetes de sistema.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Filtra los paquetes por texto en el nombre. | |
| include_system | No | Si es true, incluye paquetes de sistema (sin -3). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It correctly implies a read-only listing operation and hints at default behavior by describing the option to include system packages. However, it does not mention output format, device connection requirements, or any caveats about how the filter behaves, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence that leads with the core action and resource, then covers both configurable options without extraneous detail. It is well-structured and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the parameters are fully described, but there is no output schema and no mention of what the tool returns or what prerequisites exist, such as a connected Android device. The description is adequate for a basic list operation but could be more self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers both parameters fully with 100% coverage. The description restates the same concepts, adding no deeper semantic meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Lista') and resource ('paquetes instalados del dispositivo Android'), clearly stating what the tool does. It also mentions the two key capabilities, filtering by name and including system packages, which distinguishes it from unrelated siblings like adb_get_logcat or adb_dump_hierarchy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: whenever installed Android packages need to be listed. It does not explicitly name alternatives or exclusions, but the sibling tools are clearly unrelated operations, so the intended use case is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0adb_clear_logcatadb_dump_hierarchyadb_execute_shelladb_get_logcatadb_list_packagesEach tool targets a clear, distinct concern: logcat retrieval, logcat clearing, UI hierarchy, package listing, and shell execution. The only minor ambiguity is adb_execute_shell, which could theoretically overlap with the specialized commands if its whitelist includes similar operations.
All tools share a consistent adb_verb_noun pattern: adb_get_logcat, adb_clear_logcat, adb_dump_hierarchy, adb_list_packages, and adb_execute_shell. The naming clearly signals both the domain and the action.
Five tools is a well-scoped set for a focused Android ADB MCP server. Each tool provides meaningful functionality without adding redundant or unnecessary entries.
The set covers logcat operations, UI hierarchy, package listing, and generic safe shell execution, but lacks several common ADB operations such as screenshots, input events, package installation/uninstallation, and device information retrieval. The adb_execute_shell tool helps fill some gaps, but the overall surface is still noticeably incomplete for broad Android device testing.
Remote MCP for Android CLI agent build gate, structured receipts, audit logs, and reviewer-ready evi
MCP server for static security analysis of Android source code
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A TypeScript MCP server for Home Assistant, enabling programmatic management of entities, automati…
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Neem2004/android-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server