Emulator MCP Server

Model Context Protocol (MCP) server for controlling Android emulators from any MCP-capable client. Uses ADB and the Android emulator CLI. Control AVDs, install APKs, tap, swipe, type, take screenshots, read logs, and more—all through your AI assistant.

---

Table of contents

• Prerequisites
• Installation
• How to start the server
• Adding to clients
  • Cursor
  • VS Code & Copilot
  • Google Antigravity
  • Claude Desktop
  • Other MCP clients
• Available tools
• Troubleshooting
• References

---

Prerequisites

• Python 3.9+
• Android SDK with:
  • adb on your PATH
  • emulator on your PATH (for launching AVDs)
• (Optional) An Android Virtual Device (AVD) for emulator tools

To check:

adb version
emulator -list-avds

---

Installation

1. Clone or copy this project to a folder, e.g. android_emulator_mcp.

2. Install dependencies:

   cd android_emulator_mcp
   pip install -r requirements.txt
   

3. Verify the server loads:

   python main.py
   

   The server runs over stdio: it will start and wait for JSON-RPC messages. Normal exit is when stdin closes (e.g. the client disconnects). Use Ctrl+C to stop. You don’t need to “run” it yourself when using Cursor, VS Code, etc.—they start it automatically using the config below.

---

How to start the server

• When used by a client (Cursor, VS Code, Claude, Antigravity, etc.):
  You do not start the server yourself. The client runs the command (e.g. python) with the args (e.g. path to main.py) you configure. The server process is started and stopped by the client.

• For local testing / debugging:
  Run it in the terminal so it uses stdio and waits for input:

  cd /path/to/android_emulator_mcp
  python main.py
  

  Then either close stdin (client disconnect) or press Ctrl+C to stop.
  To test the protocol, use the official MCP inspector or another MCP client that can launch a stdio server.

• Path to Python:
  Use the same executable your client will use. Examples:

  • python or python3 if it’s on PATH
  • Full path, e.g. C:\Users\User\AppData\Local\Programs\Python\Python310\python.exe (Windows) or /usr/bin/python3 (Linux/macOS)

Replace any path below with your project path and Python path as needed.

---

Adding to clients

Cursor

The emulator server is already added to your Cursor config:

• Global (all workspaces): ~/.cursor/mcp.json — contains the emulator server with path to this project.
• This project only: .cursor/mcp.json in this repo — uses ${workspaceFolder}/main.py when you open this folder in Cursor.

If you add it manually:

1. Open Cursor Settings → Features → MCP.
2. Click + Add New MCP Server.
3. Set:
   • Name: emulator (or any name).
   • Type: stdio.
   • Command: python (or full path to python.exe).
   • Args: path to main.py, e.g.
     C:\Users\User\Documents\android_emulator_mcp\main.py
4. Save. Restart Cursor if the new server doesn’t appear.

Using the server to launch the emulator:

1. Restart Cursor (or reload the window) so it picks up mcp.json and starts the emulator MCP server.
2. Open Chat (Composer / Agent).
3. Ensure emulator (or its tools) appear under Available Tools. If not, check Settings → Features → MCP and that the server is enabled.
4. Ask the agent to use the emulator, for example:
   • “List my Android AVDs” → it can use list_avds.
   • “Launch the Android emulator for AVD <name>” → it can use launch_emulator with the AVD name.
   • “List connected devices” → it can use list_devices.

You can approve tool calls when prompted or enable Auto-run for MCP tools in agent settings.

---

VS Code & Copilot

MCP is supported in VS Code 1.102+ with Copilot. Config can be workspace (.vscode/mcp.json) or user (via MCP: Open User Configuration).

Option A – Workspace (project-only)

1. Create .vscode/mcp.json in your project.
2. Add the emulator server:

{
  "servers": {
    "emulator": {
      "type": "stdio",
      "command": "python",
      "args": ["C:\\Users\\User\\Documents\\android_emulator_mcp\\main.py"]
    }
  }
}

Use ${workspaceFolder}/main.py if main.py is inside the workspace, e.g.:

"args": ["${workspaceFolder}/android_emulator_mcp/main.py"]

Option B – User config (all projects)

1. Command Palette → MCP: Open User Configuration.
2. In the opened mcp.json, add the same servers.emulator block as above (adjust paths for your machine).

Option C – Command Palette

1. MCP: Add Server → choose stdio.
2. Command: python (or full path).
3. Args: path to main.py.
4. Choose Workspace or Global.

After adding, use Chat and ensure the emulator server (and its tools) are enabled in the tool picker. You may need to trust the server when prompted.

---

Google Antigravity

Antigravity uses a custom MCP config (e.g. Manage MCP Servers → View raw config → mcp_config.json). Add a stdio entry for this server.

1. In Antigravity, open the MCP Store (e.g. "..." at the top of the agent/side panel).
2. Click Manage MCP Servers → View raw config.
3. Edit mcp_config.json and add an entry for the emulator server. Structure is usually a map of server names to configs; use the same pattern as other stdio servers in the file. Example:

{
  "emulator": {
    "command": "python",
    "args": ["C:\\Users\\User\\Documents\\android_emulator_mcp\\main.py"]
  }
}

(or "type": "stdio" plus command / args if your Antigravity template uses that). Save and restart/reload MCP in Antigravity so it picks up the new server.

---

Claude Desktop

1. Open the Claude Desktop config file:
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
     Or: Settings → Developer → Edit Config in Claude Desktop.
2. Add the emulator under mcpServers:

{
  "mcpServers": {
    "emulator": {
      "command": "python",
      "args": ["C:\\Users\\User\\Documents\\android_emulator_mcp\\main.py"]
    }
  }
}

Use forward slashes or escaped backslashes in paths; no trailing commas. Restart Claude Desktop fully so the new server is loaded. Tools should appear (e.g. hammer icon) when the server is connected.

---

Other MCP clients

Most clients that support stdio MCP servers expect a config like:

• Command: executable to run (e.g. python, python3, or full path to Python).
• Args: list with the path to main.py.

Generic pattern:

{
  "mcpServers": {
    "emulator": {
      "command": "python",
      "args": ["/absolute/path/to/android_emulator_mcp/main.py"]
    }
  }
}

Or with type (if the client requires it):

{
  "emulator": {
    "type": "stdio",
    "command": "python",
    "args": ["C:\\Users\\User\\Documents\\android_emulator_mcp\\main.py"]
  }
}

Replace the path with your actual android_emulator_mcp path. Then point your client at this config (or merge this block into its MCP config).

---

Available tools

Tool	Description
launch_emulator	Launch an AVD in the background
kill_emulator	Kill the Android emulator
restart_emulator_cold_boot	Use when emulator is hanging: kill, wait 25s, then cold boot (avoids PC freeze)
list_avds	List available Android Virtual Devices
list_devices	List connected devices/emulators
install_apk	Install an APK on the device
uninstall_app	Uninstall an app by package name
launch_app	Launch an app by package (optional activity)
tap_screen	Tap at (x, y) coordinates
swipe	Swipe from one point to another
type_text	Type text on the device
press_key	Send key event (BACK, HOME, ENTER, etc.)
batched_input	Execute multiple input actions in one call
get_ui_hierarchy	Get UI XML tree (bounds, text, IDs)
click_element_by_text	Find and tap element by visible text
start_activity_with_data	Launch via Deep Link (URI)
set_gps_location	Set emulator GPS (lat, lng)
get_screen_info	Get device screen resolution
take_screenshot	Capture screenshot (optional scale 0.1–1.0)
read_logs	Read logcat (optional filter)
get_logcat_stream	Last N lines, filter by tag
clear_logs	Clear logcat buffer
check_network_condition	Test emulator internet access
get_emulator_stats	Memory/CPU usage
record_screen	Record screen as MP4
pull_file	Pull file from device to host
push_file	Push file from host to device
shell_command	Run arbitrary adb shell command

---

Troubleshooting

• “adb: command not found” / “emulator: command not found”
  Add the Android SDK platform-tools and emulator directories to your PATH.

• PC or Cursor hangs when killing / launching emulator
  What we fix: The server uses a timeout (8 s) for adb emu kill. If the emulator is hung, the command stops after 8 s and on Windows the server force-kills emulator.exe / qemu-system-*.exe so your machine doesn’t stay stuck. What we don't fix: The whole PC can still freeze from load. Killing then immediately cold-booting is very heavy; on 16 GB / i5 that often causes a hang. What to do: Use restart_emulator_cold_boot(avd_name) only—it kills, waits 25 s, then cold boots in one call. Do not call kill_emulator and launch_emulator separately or the PC may freeze. Close other apps first on 16 GB / i5.

• Server not showing in Cursor
  Confirm the path to main.py in Args is correct and that python (or the full path) runs main.py without errors. Restart Cursor and check Features → MCP for the server and any error state.

• VS Code: server not starting / not trusted
  Run MCP: List Servers, select the emulator server, and use Show Output to see logs. Use MCP: Reset Trust if you need to be prompted to trust again.

• Claude Desktop: tools never appear
  Restart Claude Desktop completely (quit and reopen). Ensure the config JSON is valid (no trailing commas). Check that python and the path in args are correct.

• Paths with spaces
  Use quoted paths in configs where required. For args, a single string like "C:\\Users\\User\\Documents\\android_emulator_mcp\\main.py" is typical; avoid splitting the path across multiple args.

---

References

• Model Context Protocol
• Cursor – MCP
• VS Code – Use MCP servers
• Antigravity – MCP
• MCP servers (GitHub)