AVD MCP Server

A Model Context Protocol (MCP) server for Android Virtual Device automation. This tool allows you to start an Android 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

Prerequisites

• Android SDK with adb and emulator in PATH

• Node.js 18 or higher

• An Android Virtual Device configured in Android Studio

Installation

Quick Start (Recommended)

No installation needed! Just add to your MCP client config (e.g., Claude Desktop):

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

That's it! The package will be automatically downloaded and executed when needed.

Local Development

``bash

Clone the repository

git clone https://github.com/yourusername/avd-mcp.git cd avd-mcp

Install dependencies

pnpm install

Build the project

pnpm build

Test locally

node dist/index.js ``

Usage

Available Tools

avd_run_and_screenshot

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

Parameters:

• avdName (optional): Name of the AVD to start. If omitted and no device is running, will throw an error.

• command (required): Command to execute (e.g., pnpm android, gradle assembleDebug)

• waitMsAfterRun (optional): Milliseconds to wait after command execution before taking screenshot. Default: 2000ms

Returns:

• Command output (stdout/stderr)

• Screenshot in base64 format (PNG)

Example:

typescript { "avdName": "Pixel_5_API_31", "command": "pnpm android", "waitMsAfterRun": 5000 }

How It Works

1. Device Check: Checks if an Android device/emulator is already running using adb devices

2. Start Emulator: If no device is running and avdName is provided, starts the emulator

3. Execute Command: Runs the specified command using PowerShell

4. Wait: Waits for the specified duration to allow UI updates

5. Screenshot: Captures a screenshot using adb screencap

6. Return: Returns both command output and screenshot

Troubleshooting

AVD not starting

• Verify AVD name matches one configured in Android Studio: emulator -list-avds

• Check that emulator is in your system PATH

• Ensure virtualization is enabled in BIOS (Intel VT-x or AMD-V)

ADB not found

• Install Android SDK Platform-Tools

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

Screenshot timeout

• Increase waitMsAfterRun parameter

• Check if device is fully booted: adb shell getprop sys.boot_completed (should return 1)

Publishing to npm

To publish this package to npm:

``bash

Login to npm

npm login

Update version in package.json

npm version patch # or minor, or major

Publish

npm publish ``

After publishing, users can use it directly with npx avd-mcp without cloning!

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Author

Created for automating Android development workflows with AI assistants.