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.

1. Install dependencies:

   cd android_emulator_mcp
   pip install -r requirements.txt

1. 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

1. 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.

1. 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)