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
adbandemulatorin 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
- Device Check: Checks if an Android device/emulator is already running using
adb devices - Start Emulator: If no device is running and
avdNameis provided, starts the emulator - Execute Command: Runs the specified command using PowerShell
- Wait: Waits for the specified duration to allow UI updates
- Screenshot: Captures a screenshot using
adb screencap - 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
emulatoris 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
waitMsAfterRunparameter - Check if device is fully booted:
adb shell getprop sys.boot_completed(should return1)
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.