AVD MCP Server

A Model Context Protocol (MCP) server for Android Virtual Device automation. It can start an emulator, execute commands, and capture screenshots automatically.

Features

• Automatically starts Android Virtual Device (AVD) if not running

• Executes commands (pnpm, gradle, npm, etc.)

• Captures screenshots from the emulator

• Returns command output and screenshot in base64 format

• Supports serial selection for device-specific actions

• Structured logs and standardized tool errors for better observability

Prerequisites

• Android SDK with adb and emulator in PATH

• Node.js 18 or higher

• At least one AVD configured in Android Studio

• Shell available for command execution (powershell on Windows, sh on Linux/macOS, with bash and zsh fallback)

Installation

Quick Start

No installation needed. Add this to your MCP client config:

{
  "mcpServers": {
    "avd-mcp": {
      "command": "npx",
      "args": ["avd-mcp"]
    }
  }
}

Local Development

git clone https://github.com/jramalho/avd-mcp.git
cd avd-mcp
pnpm install
pnpm build
node dist/index.js

Usage

Project organization for new MCP tools

Keep a consistent pattern for every new tool:

src/
  application/
    <tool-name>-use-case.ts
  mcp/tools/
    definitions.ts             # inputSchema MCP + zod schemas
    handler.ts                 # dispatcher + error/log wrapper
  adapters/node/
    <integration>-adapter.ts
    command-helpers.ts          # runAdb, runEmulator, timeouts
  ports/
    <integration>-port.ts
  shared/
    errors/tool-error.ts        # friendly + technical error model
    logging/logger.ts           # structured JSON logs
  tests/
    mcp-smoke-test.ts           # E2E MCP smoke test via stdio client
  index.ts                      # bootstrap do servidor e wiring de dependências

Naming convention:

• Tool name: avd_<action> (example: avd_start, avd_stop)

• Use case class: <Action>AvdUseCase or <Action>UseCase

• Port interface: <Capability>Port

• Adapter class: <Runtime><Capability>Adapter (example: AdbAdapter)

Implementation baseline for every tool:

• Strong TypeScript typing in input/output contracts and ports

• Zod schema validation in index.ts

• Friendly error + technical details using ToolError

• Structured logs via Logger (tool_call_started, tool_call_succeeded, tool_call_failed)

• Optional serial parameter whenever action can target a specific device

• CI-ready options (noWindow: true, optional gpuMode: "swiftshader_indirect")

Tool: avd_list

Lists available AVDs from emulator -list-avds.

Tool: avd_start

Starts an AVD with boot options.

Parameters:

• avdName (optional)

• coldBoot (optional): Uses -no-snapshot-load.

• wipeData (optional): Uses -wipe-data.

• noWindow (optional): Uses -no-window.

• readOnly (optional): Uses -read-only.

• gpuMode (optional): Uses -gpu, allowed values: auto, host, swiftshader_indirect.

• waitForBoot (optional): Wait for an online device before returning. Default true.

Tool: avd_stop

Stops an online emulator using adb emu kill.

Parameters:

• serial (optional): Emulator serial (example: emulator-5554). If omitted, stops the first online emulator.

Tool: avd_status

Retorna status dos devices conhecidos pelo adb devices em formato estruturado (JSON serializável).

Parameters:

• serial (optional): Se informado, retorna status detalhado só desse device.

Output (shape):

• requestedSerial (opcional)

• generatedAt

• devices[] com: serial, state, isEmulator, avdName (quando disponível), bootCompleted

• summary com contagens agregadas

Tool: avd_restart

Reinicia um emulador: executa adb emu kill, espera sair do adb devices e inicia novamente reaproveitando a lógica de avd_start.

Parameters:

• serial (optional): Emulator serial alvo. Se omitido, usa o primeiro emulador online.

• coldBoot (optional): Uses -no-snapshot-load.

• wipeData (optional): Uses -wipe-data.

• noWindow (optional): Uses -no-window.

• readOnly (optional): Uses -read-only.

• gpuMode (optional): Uses -gpu, allowed values: auto, host, swiftshader_indirect.

• waitForBoot (optional): Aguarda boot completo (sys.boot_completed=1) antes de retornar.

Output (shape):

• traceId

• targetSerial

• avdName

• stopDurationMs

• startDurationMs

• totalDurationMs

• onlineDevicesAfterRestart

Tool: avd_run_and_screenshot

Starts an AVD (if needed), executes a command, waits, and captures a screenshot.

Parameters:

• avdName (optional): AVD name. If omitted and no device is online, the first available AVD from emulator -list-avds is used.

• serial (optional): Target online device serial (example: emulator-5554). If provided, no auto-start is attempted.

• command (required): Command to execute.

• coldBoot (optional): Uses -no-snapshot-load.

• wipeData (optional): Uses -wipe-data.

• noWindow (optional): Uses -no-window.

• readOnly (optional): Uses -read-only.

• gpuMode (optional): Uses -gpu, allowed values: auto, host, swiftshader_indirect.

• waitMsAfterRun (optional): Wait time before screenshot. Default 2000.

Example:

{
  "avdName": "Pixel_5_API_31",
  "serial": "emulator-5554",
  "coldBoot": true,
  "noWindow": false,
  "readOnly": false,
  "gpuMode": "host",
  "command": "pnpm android",
  "waitMsAfterRun": 5000
}

Tool: adb_install_apk

Instala APK no device via adb install -r.

Parameters:

• serial (optional): Serial alvo.

• apkPath (required): Caminho local do APK.

• timeoutMs (optional): Timeout da execução.

Tool: adb_uninstall

Remove pacote do device via adb uninstall.

Parameters:

• serial (optional): Serial alvo.

• packageName (required): Exemplo com.example.app.

• timeoutMs (optional): Timeout da execução.

Tool: adb_shell

Executa adb shell <command> em safe mode.

Parameters:

• serial (optional): Serial alvo.

• command (required): Comando shell único.

• timeoutMs (optional): Timeout da execução.

Tool: adb_logcat

Lê logcat com timeout curto e limite de linhas.

Parameters:

• serial (optional): Serial alvo.

• filter (optional): Filtro de prioridade/tag.

• maxLines (optional): Quantidade máxima de linhas retornadas.

• timeoutMs (optional): Timeout da execução.

Tool: screenrecord_start

Inicia gravação de tela com adb shell screenrecord e retorna sessionId para finalização posterior.

Parameters:

• serial (optional): Serial alvo.

• maxDurationSeconds (optional): Limite máximo da gravação. Default 120.

• bitRate (optional): Bitrate do vídeo (ex.: 4000000).

• size (optional): Resolução (ex.: 1280x720).

Tool: screenrecord_stop

Finaliza gravação por sessionId, faz pull do arquivo para artifacts e remove o arquivo temporário do device.

Parameters:

• sessionId (required): Session retornada por screenrecord_start.

• serial (optional): Validado contra a sessão ativa.

• inlineBase64 (optional): Retorna vídeo em base64 no payload.

Tool: screenshot

Captura screenshot com suporte a crop, compressão e anotação textual.

Parameters:

• serial (optional): Serial alvo.

• crop (optional): { x, y, width, height }.

• compressQuality (optional): 0 a 100.

• annotate (optional): lista de textos { text, x, y }.

• inlineBase64 (optional): Retorna PNG em base64 no payload.

Tool: network_toggle

Liga/desliga wifi, dados móveis e modo avião.

Parameters:

• serial (optional): Serial alvo.

• wifiEnabled (required): Liga/desliga wifi.

• dataEnabled (optional): Liga/desliga dados móveis.

• airplaneMode (optional): Liga/desliga modo avião.

Tool: network_condition

Aplica condição de rede no emulador por perfil pronto (good, slow_3g, lte, offline) ou perfil avançado.

Parameters:

• serial (optional): Serial alvo.

• profile (required):

  • string: good | slow_3g | lte | offline

  • objeto avançado: { latencyMs?, packetLoss?, speedKbps? }

Tool: set_location

Define coordenadas GPS no emulador via adb emu geo fix <lon> <lat>.

Parameters:

• serial (optional): Serial alvo.

• latitude (required): entre -90 e 90.

• longitude (required): entre -180 e 180.

Tool: set_battery_state

Define nível e estado de carga da bateria via dumpsys battery.

Parameters:

• serial (optional): Serial alvo.

• level (optional): 0 a 100.

• charging (optional): true para carregando, false para descarregando.

Tool: set_rotation

Define orientação da tela via settings put system.

Parameters:

• serial (optional): Serial alvo.

• orientation (required): portrait | landscape.

Tool: set_locale

Define locale via setprop e broadcast de locale.

Parameters:

• serial (optional): Serial alvo.

• language (required): ex. pt, en.

• country (optional): ex. BR, US.

API level limitations

Alguns comandos variam entre versões de Android e builds de sistema (AOSP/OEM). Em especial, svc data, settings put global airplane_mode_on, dumpsys battery set ..., user_rotation e mudanças de locale por setprop podem exigir permissões diferentes, reboot, restart de app ou podem não surtir efeito imediato em APIs mais novas. Para estabilidade em CI, prefira emuladores AOSP com API fixa por pipeline e valide a efetividade no app (não apenas o exit code do adb).

Structured logging

O servidor usa logging estruturado em src/observability/logger.ts com logInfo, logWarn e logError, sempre com payload { traceId, tool, message, data? }.

• Formato humano (default): linha legível para terminal.

• Formato JSON (uma linha por evento): habilite com AVD_MCP_JSON_LOGS=true.

Todas as tools MCP registram início e fim da execução com durationMs, incluindo tool, traceId, deviceId e success (true/false) nos logs de conclusão.

Formato padrão de erro das tools

Quando uma tool falha, a resposta textual retorna um JSON padronizado com os campos:

• code: código curto da falha.

• message: mensagem legível para humano.

• hints (opcional): sugestões de correção.

• validOptions (opcional): opções válidas para o campo.

Exemplo geral:

{
  "code": "INVALID_INPUT",
  "message": "Parâmetros inválidos para avd_start.",
  "hints": ["Verifique os campos obrigatórios."],
  "validOptions": null
}

Exemplo: avd_start com avdName inválido

{
  "code": "AVD_NOT_FOUND",
  "message": "avdName \"Pixel_7_Pro_API_36\" não encontrado.",
  "hints": ["Você quis dizer Pixel_7_Pro_API_35?"],
  "validOptions": [
    "Pixel_7_Pro_API_35",
    "Pixel_8_API_34",
    "Medium_Tablet_API_34"
  ]
}

Exemplo: avd_start com gpuMode inválido

{
  "code": "INVALID_GPU_MODE",
  "message": "gpuMode inválido: vulkan.",
  "hints": ["Use um dos valores suportados: auto, host, swiftshader_indirect."],
  "validOptions": ["auto", "host", "swiftshader_indirect"]
}

Exemplo: adb_shell com comando proibido

{
  "code": "SHELL_COMMAND_NOT_ALLOWED",
  "message": "Comando não permitido em safe mode. Comandos permitidos: pm list packages [filtro], pm grant <package> <permission>, pm clear <package>, am start ..., am force-stop <package>, monkey -p <package> -c android.intent.category.launcher 1, svc wifi enable|disable, svc data enable|disable, settings put|get (global|system) ..., dumpsys battery, dumpsys battery set level|status|plugged <valor>, dumpsys battery reset, getprop [key], setprop persist.sys.locale|language|country <valor>, rm /sdcard/mcp_record_<timestamp>.mp4, input keyevent|tap|swipe|text ...",
  "hints": ["Use adb_shell apenas para comandos na allowlist."],
  "validOptions": [
    "pm list packages [filtro]",
    "pm grant <package> <permission>",
    "pm clear <package>",
    "am start ...",
    "am force-stop <package>",
    "monkey -p <package> -c android.intent.category.launcher 1",
    "svc wifi enable|disable",
    "svc data enable|disable",
    "settings put|get (global|system) ...",
    "dumpsys battery",
    "dumpsys battery set level|status|plugged <valor>",
    "dumpsys battery reset",
    "getprop [key]",
    "setprop persist.sys.locale|language|country <valor>",
    "rm /sdcard/mcp_record_<timestamp>.mp4",
    "input keyevent|tap|swipe|text ..."
  ]
}

Safe mode e allowlist

O servidor valida todos os comandos adb shell em uma função central (src/adb/shell-safety.ts) com allowlist de padrões permitidos. Com isso, comandos fora da lista são bloqueados com erro de segurança.

Com AVD_MCP_SAFE_MODE=true (default), há bloqueios extras para comandos perigosos, incluindo:

• reboot e reboot bootloader

• rm destrutivo (ex.: rm -rf /, remoções em áreas críticas)

• format e wipe fora de fluxos controlados

Para desenvolvimento local, é possível desativar o modo estrito com AVD_MCP_SAFE_MODE=false. Mesmo assim, a allowlist continua ativa.

Não desative safeMode em CI/prod: isso reduz proteção contra comandos destrutivos e aumenta risco operacional em hosts compartilhados.

Segurança de paths e comandos

• Inputs de comando são sanitizados (sem quebra de linha, sem \0, etc.).

• Paths locais recebidos por tools são validados para ficar dentro da pasta base.

• Pasta base padrão: diretório atual do processo (process.cwd()), configurável por AVD_MCP_WORKSPACE_DIR.

Tool: get_metrics

Retorna métricas simples desde o start do processo.

Output (shape):

• startedAt

• uptimeMs

• totalExecutions

• tools[] com: tool, executions, avgDurationMs

Media configuration

• MCP_ARTIFACTS_DIR: diretório raiz de artifacts (default .artifacts).

• MCP_INLINE_BASE64: padrão global para retorno base64 (true/false, default false).

• Estrutura de saída:

  • ${MCP_ARTIFACTS_DIR}/records/<sessionId>.mp4

  • ${MCP_ARTIFACTS_DIR}/screenshots/<timestamp>_<traceId>.png

MCP client call examples

From a client perspective, calls follow this shape:

{
  "method": "tools/call",
  "params": {
    "name": "<tool-name>",
    "arguments": {}
  }
}

Example: list AVDs

{
  "method": "tools/call",
  "params": {
    "name": "avd_list",
    "arguments": {}
  }
}

Example: start headless for CI

{
  "method": "tools/call",
  "params": {
    "name": "avd_start",
    "arguments": {
      "avdName": "Pixel_5_API_31",
      "noWindow": true,
      "gpuMode": "swiftshader_indirect",
      "waitForBoot": true
    }
  }
}

Example: run command + screenshot in a specific serial

{
  "method": "tools/call",
  "params": {
    "name": "avd_run_and_screenshot",
    "arguments": {
      "serial": "emulator-5554",
      "command": "pnpm android",
      "waitMsAfterRun": 4000
    }
  }
}

Example: stop a specific emulator

{
  "method": "tools/call",
  "params": {
    "name": "avd_stop",
    "arguments": {
      "serial": "emulator-5554"
    }
  }
}

Example: get status from all devices

{
  "method": "tools/call",
  "params": {
    "name": "avd_status",
    "arguments": {}
  }
}

Example: get status for one serial

{
  "method": "tools/call",
  "params": {
    "name": "avd_status",
    "arguments": {
      "serial": "emulator-5554"
    }
  }
}

Example: restart one emulator (headless, wait boot)

{
  "method": "tools/call",
  "params": {
    "name": "avd_restart",
    "arguments": {
      "serial": "emulator-5554",
      "noWindow": true,
      "gpuMode": "swiftshader_indirect",
      "waitForBoot": true
    }
  }
}

Example: install APK

{
  "method": "tools/call",
  "params": {
    "name": "adb_install_apk",
    "arguments": {
      "serial": "emulator-5554",
      "apkPath": "C:\\builds\\app-debug.apk",
      "timeoutMs": 120000
    }
  }
}

Example: uninstall package

{
  "method": "tools/call",
  "params": {
    "name": "adb_uninstall",
    "arguments": {
      "serial": "emulator-5554",
      "packageName": "com.example.app"
    }
  }
}

Example: adb shell (safe mode)

{
  "method": "tools/call",
  "params": {
    "name": "adb_shell",
    "arguments": {
      "serial": "emulator-5554",
      "command": "pm list packages"
    }
  }
}

Example: adb logcat (simple)

{
  "method": "tools/call",
  "params": {
    "name": "adb_logcat",
    "arguments": {
      "serial": "emulator-5554",
      "filter": "*:E",
      "maxLines": 100,
      "timeoutMs": 4000
    }
  }
}

Example: start screenrecord

{
  "method": "tools/call",
  "params": {
    "name": "screenrecord_start",
    "arguments": {
      "serial": "emulator-5554",
      "maxDurationSeconds": 60,
      "bitRate": 4000000,
      "size": "1280x720"
    }
  }
}

Example: stop screenrecord

{
  "method": "tools/call",
  "params": {
    "name": "screenrecord_stop",
    "arguments": {
      "sessionId": "<SESSION_ID>",
      "serial": "emulator-5554",
      "inlineBase64": false
    }
  }
}

Example: screenshot with crop + annotate

{
  "method": "tools/call",
  "params": {
    "name": "screenshot",
    "arguments": {
      "serial": "emulator-5554",
      "crop": {
        "x": 100,
        "y": 200,
        "width": 900,
        "height": 1600
      },
      "compressQuality": 80,
      "annotate": [
        { "text": "Login", "x": 120, "y": 240 },
        { "text": "CTA", "x": 500, "y": 1500 }
      ],
      "inlineBase64": false
    }
  }
}

Example: network slow 3G profile

{
  "method": "tools/call",
  "params": {
    "name": "network_condition",
    "arguments": {
      "serial": "emulator-5554",
      "profile": "slow_3g"
    }
  }
}

Example: toggle airplane mode

{
  "method": "tools/call",
  "params": {
    "name": "network_toggle",
    "arguments": {
      "serial": "emulator-5554",
      "wifiEnabled": false,
      "dataEnabled": false,
      "airplaneMode": true
    }
  }
}

Example: set Curitiba location

{
  "method": "tools/call",
  "params": {
    "name": "set_location",
    "arguments": {
      "serial": "emulator-5554",
      "latitude": -25.4284,
      "longitude": -49.2733
    }
  }
}

Example: set low battery not charging

{
  "method": "tools/call",
  "params": {
    "name": "set_battery_state",
    "arguments": {
      "serial": "emulator-5554",
      "level": 5,
      "charging": false
    }
  }
}

Example: set locale pt-BR

{
  "method": "tools/call",
  "params": {
    "name": "set_locale",
    "arguments": {
      "serial": "emulator-5554",
      "language": "pt",
      "country": "BR"
    }
  }
}

Automated scenario runners

Para validar fluxos ponta a ponta no MCP, use os runners abaixo:

• pnpm test:adb-tools: cenários de install/uninstall/shell/logcat.

• pnpm test:media-tools: cenários de screenrecord e screenshot (crop/annotate/base64).

• pnpm test:network-device-tools: cenários de rede, localização, locale e bateria.

Todos os runners geram relatório OK/FAIL no terminal e retornam código de saída 1 quando existe falha em cenário.

Troubleshooting

Emulator not starting

• Check available AVDs with emulator -list-avds

• Ensure emulator is in PATH

• Ensure virtualization is enabled (Intel VT-x / AMD-V)

ADB not found

• Install Android SDK Platform-Tools

• Add platform-tools to PATH (example): C:\Users\YourUser\AppData\Local\Android\Sdk\platform-tools

License

MIT License - see LICENSE.