MCP-MEmu

AI-Powered Android Emulator Control via Model Context Protocol

by Devbysatyam @ Avion

Features • Quick Start • Use Cases • Tools • Prompts • Security • Architecture

🌟 What is MCP-MEmu?

MCP-MEmu is a Model Context Protocol (MCP) server that gives AI agents complete control over MEmu Android Emulator. It wraps the MEMUC CLI through PyMEMUC and exposes 69 tools, 8 resources, and 7 prompt templates for seamless AI-driven Android automation.

Connect it to Claude Desktop, Antigravity, Cursor, or any MCP-compatible client — and your AI can boot VMs, install apps, automate UI, take screenshots, spoof GPS, transfer files, and much more.

✨ Features

🎮 69 Automation Tools

Category	Count	Highlights
🔄 Lifecycle	15	Create, clone, start, stop, reboot, delete, export/import VMs
⚙️ Configuration	8	CPU, RAM, resolution, GPS, IMEI, device fingerprint randomization
📱 App Management	7	Install APK, launch, stop, uninstall, clear data, list packages
👆 UI Interaction	14	Tap, swipe, long press, text input, keys, scroll, rotate, zoom, shake
📸 Screenshot	3	Save to file, base64 for AI vision, get screen dimensions
🌐 Network & Sensors	6	Connect/disconnect, GPS spoofing, accelerometer, public IP
💻 Shell & Advanced	8	Shell commands, ADB passthrough, file push/pull, clipboard
🚀 Compound	8	Boot & ready, fresh start app, batch install, monkey test, snapshots

📚 8 MCP Resources (LLM Context)

Resource	Description
`memu://guide`	Comprehensive getting started guide with anti-hallucination rules
`memu://tools`	Complete tool reference with all args and descriptions
`memu://workflows`	Step-by-step automation recipes
`memu://config-keys`	All VM configuration keys with valid values
`memu://vms`	Live VM list with status (dynamic)
`memu://vm/{index}/status`	Individual VM status (dynamic)
`memu://security`	Security model documentation

💡 7 Prompt Templates (Guided Workflows)

Prompt	Description
`automate_app_testing`	Full app testing workflow with screenshot-first rules
`setup_new_vm`	Create → configure → boot from scratch
`ui_automation_guide`	Screen coordinate system, swipe directions, input reference
`batch_device_farm`	Set up multiple VMs with diverse configs
`debug_vm_issues`	Diagnostic flowchart with error → fix mapping
`gps_spoofing_guide`	10 city presets with verification steps
`file_transfer_guide`	Push/pull files with VM path reference

🛡️ Security

Protected VM Registry — Pre-existing VMs cannot be deleted/stopped/renamed
Input Validation — VM index validation, dangerous command blocklist
Audit Logging — All destructive operations logged with timestamps
Command Blocklist — Blocks rm -rf /, mkfs, dd, reboot, shutdown, format, wipe

🚀 Quick Start

Prerequisites

Requirement	Details
OS	Windows 10/11
MEmu Player	Download (installed & working)
Python	3.10 or higher
uv	Install — Python package manager
Admin Privileges	Required by MEMUC CLI

Installation

# Clone the repository git clone https://github.com/devbysatyam/mcp-memu.git cd mcp-memu # Install dependencies uv sync

Run the Server

# Start the MCP server (stdio transport) python server.py # Or test with MCP Inspector (opens browser UI) mcp dev server.py

Connect to Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json:

{ "mcpServers": { "memu": { "command": "uv", "args": ["run", "--directory", "C:\\path\\to\\mcp-memu", "python", "server.py"] } } }

Connect to Antigravity / Gemini

Add to your MCP server settings:

{ "memu": { "command": "uv", "args": ["run", "--directory", "C:\\path\\to\\mcp-memu", "python", "server.py"] } }

📖 Use Cases

1. 📱 Automated App Testing

"Install my APK, launch it, go through the onboarding flow, and take screenshots at each step."

The AI agent will:

Boot the VM and wait for Android to fully load
Install your APK via install_apk
Launch the app and take a screenshot to see the screen
Navigate through UI using tap, swipe, input_text
Capture screenshots at each step for visual verification

Tools used: boot_and_ready → install_apk → launch_app → screenshot_base64 → tap → input_text → take_screenshot

2. 🌍 GPS-Based Testing

"Set the location to San Francisco and check if the app shows nearby restaurants."

Tools used: set_gps_location(lat=37.7749, lng=-122.4194) → launch_app → screenshot_base64

3. 🏭 Device Farm Setup

"Create 3 VMs with different resolutions and device fingerprints for compatibility testing."

The AI agent will:

Create 3 new Android 9 VMs
Configure each with different CPU, RAM, resolution
Randomize device fingerprints so each looks unique
Boot all VMs and verify they're working

Tools used: create_vm (x3) → set_vm_cpu → set_vm_memory → set_vm_resolution → randomize_vm_device → boot_and_ready

4. 🔄 CI/CD Integration

"Run a monkey test on the app and capture the results."

Tools used: boot_and_ready → install_apk → run_monkey_test → take_screenshot → pull_file (logs)

5. 📋 Clipboard & File Transfer

"Push a config file to the VM, read back the app's output log."

Tools used: push_file → launch_app → pull_file → set_clipboard → get_clipboard

6. 🔧 VM Configuration Management

"Read current config, change to 4 CPU cores and 4GB RAM, then reboot."

Tools used: get_all_vm_config → stop_vm → set_vm_cpu(cores=4) → set_vm_memory(mb=4096) → boot_and_ready

🔧 Tool Reference

Lifecycle Management

Tool	Description	Key Args
`list_vms`	List all VMs with status	—
`get_vm_status`	Check running/stopped	`vm_index`
`start_vm`	Boot a VM	`vm_index`
`stop_vm`	Graceful shutdown	`vm_index`
`reboot_vm`	Restart a VM	`vm_index`
`create_vm`	Create new VM	`vm_version` (76=Android 7, 96=Android 9)
`delete_vm`	Permanently delete	`vm_index`
`clone_vm`	Clone existing VM	`vm_index`, `new_name`
`rename_vm`	Rename a VM	`vm_index`, `new_name`
`export_vm`	Export to .ova	`vm_index`, `output_path`
`import_vm`	Import from .ova	`ova_path`
`compress_vm`	Compress disk	`vm_index`
`sort_out_all_vms`	Re-tile windows	—
`stop_all_vms`	Stop all non-protected	—
`check_task_status`	Async task status	`task_id`

Configuration

Tool	Description	Key Args
`get_all_vm_config`	Read all common settings	`vm_index`
`get_vm_config`	Read single setting	`vm_index`, `key`
`set_vm_config`	Write single setting	`vm_index`, `key`, `value`
`set_vm_cpu`	Set CPU cores	`vm_index`, `cores` (1/2/4/8)
`set_vm_memory`	Set RAM	`vm_index`, `mb`
`set_vm_resolution`	Set display	`vm_index`, `width`, `height`, `dpi`
`set_vm_gps`	Set GPS	`vm_index`, `lat`, `lng`
`randomize_vm_device`	Random fingerprint	`vm_index`

App Management

Tool	Description	Key Args
`list_apps`	Installed packages	`vm_index`
`install_apk`	Install APK file	`vm_index`, `apk_path`
`uninstall_app`	Remove app	`vm_index`, `package`
`launch_app`	Start app	`vm_index`, `package`
`stop_app`	Force stop	`vm_index`, `package`
`clear_app_data`	Wipe app data	`vm_index`, `package`
`create_app_shortcut`	Desktop shortcut	`vm_index`, `package`

UI Interaction

Tool	Description	Key Args
`tap`	Tap coordinates	`vm_index`, `x`, `y`
`swipe`	Swipe gesture	`vm_index`, `x1`, `y1`, `x2`, `y2`, `duration_ms`
`long_press`	Long press	`vm_index`, `x`, `y`, `duration_ms`
`input_text`	Type text	`vm_index`, `text`
`send_key`	Send key event	`vm_index`, `key` (home/back/menu/volumeup/volumedown)
`press_enter`	Enter key	`vm_index`
`press_back`	Back button	`vm_index`
`press_home`	Home button	`vm_index`
`shake_device`	Shake gesture	`vm_index`
`rotate_screen`	Toggle orientation	`vm_index`
`zoom_in` / `zoom_out`	Pinch zoom	`vm_index`
`scroll_up` / `scroll_down`	Scroll	`vm_index`, `x`

Screenshot & Capture

Tool	Description	Key Args
`take_screenshot`	Save to file	`vm_index`, `save_path`
`screenshot_base64`	Base64 PNG for AI vision	`vm_index`
`get_screen_size`	Current resolution	`vm_index`

Network & Sensors

Tool	Description	Key Args
`connect_network`	Enable internet	`vm_index`
`disconnect_network`	Disable internet	`vm_index`
`get_public_ip`	Get public IP	`vm_index`
`set_gps_location`	Spoof GPS	`vm_index`, `lat`, `lng`
`set_accelerometer`	Set sensor	`vm_index`, `x`, `y`, `z`
`get_adb_connection_info`	Get ADB address	`vm_index`

Shell & Advanced

Tool	Description	Key Args
`execute_shell`	Run shell command	`vm_index`, `command`
`send_adb`	Raw ADB command	`vm_index`, `command`
`get_device_info`	Model/version/CPU	`vm_index`
`get_running_apps`	Running processes	`vm_index`
`pull_file`	VM → Host	`vm_index`, `remote_path`, `local_path`
`push_file`	Host → VM	`vm_index`, `local_path`, `remote_path`
`set_clipboard`	Set clipboard	`vm_index`, `text`
`get_clipboard`	Read clipboard	`vm_index`

Compound (Multi-Step)

Tool	Description
`wait_for_boot`	Poll until Android is fully booted
`boot_and_ready`	Start VM + wait for boot
`fresh_start_app`	Stop → clear data → relaunch
`install_and_launch`	Install APK + launch
`clone_and_configure`	Clone + set CPU/RAM/resolution
`batch_install`	Install multiple APKs (`;`-separated)
`full_vm_snapshot`	Stop → export → restart
`run_monkey_test`	Random UI stress test

🏗️ Architecture

┌─────────────────────────────────────────────────────┐ │ MCP Client │ │ (Claude Desktop / Antigravity / Cursor / etc.) │ └───────────────────────┬─────────────────────────────┘ │ JSON-RPC (stdio) ┌───────────────────────┴─────────────────────────────┐ │ MCP-MEmu Server │ │ server.py │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ Tools │ │Resources │ │ Prompts │ │ │ │ (69) │ │ (8) │ │ (7 templates) │ │ │ └────┬─────┘ └──────────┘ └──────────────────┘ │ │ │ │ │ ┌────┴──────────────────────────────────────────┐ │ │ │ Security Layer │ │ │ │ • Protected VM registry │ │ │ │ • Input validation & command blocklist │ │ │ │ • Audit logging │ │ │ └────┬──────────────────────────────────────────┘ │ │ │ │ │ ┌────┴──────────────────────────────────────────┐ │ │ │ PyMEMUC + ADB Helpers │ │ │ │ • MEMUC CLI wrapper │ │ │ │ • ADB pull/push with auto-reconnect │ │ │ └────┬──────────────────────────────────────────┘ │ └───────┴──────────────────────────────────────────────┘ │ ┌───────┴──────────────────────────────────────────────┐ │ MEmu Android Emulator │ │ (MEMUC CLI + ADB over TCP) │ └──────────────────────────────────────────────────────┘

📁 Project Structure

mcp-memu/ ├── assets/ │ └── banner.png # GitHub banner image ├── tools/ │ ├── lifecycle.py # VM start, stop, create, delete, clone │ ├── config.py # CPU, RAM, resolution, GPS settings │ ├── apps.py # Install, launch, stop apps │ ├── input.py # Tap, swipe, type, scroll, shake │ ├── capture.py # Screenshots (file & base64) │ ├── network.py # Network, GPS, accelerometer │ ├── shell.py # Shell, ADB, file transfer, clipboard │ └── compound.py # High-level combined operations ├── resources/ │ ├── vm_status.py # MCP resources (guides, tools ref, config keys) │ └── prompts.py # MCP prompt templates (7 workflows) ├── utils/ │ ├── memuc_instance.py # Singleton PyMemuc + security layer │ └── adb_helpers.py # ADB pull/push with timeout & reconnect ├── server.py # FastMCP entry point ├── pyproject.toml # Project metadata & dependencies ├── protected_vms.json # Auto-generated (gitignored) ├── SECURITY.md # Security documentation ├── LICENSE # MIT License └── README.md # This file

📦 Dependencies

Package	Version	Purpose
pymemuc	≥ 0.6.0	Python wrapper for MEmu's MEMUC CLI
mcp[cli]	≥ 1.0.0	Model Context Protocol SDK + CLI tools
Pillow	≥ 12.1.1	Image processing for screenshots

All dependencies are managed via pyproject.toml and installed automatically with uv sync.

🔒 Security

See SECURITY.md for full details.

Feature	Description
Protected VMs	Pre-existing VMs snapshotted on startup — cannot be deleted/stopped
Input Validation	VM index validated, negative values rejected
Command Blocklist	`rm -rf /`, `mkfs`, `dd`, `reboot`, `shutdown`, `format`, `wipe` blocked
Audit Logging	All destructive ops logged with timestamps to stderr
Local-Only Transport	Uses stdio — no network exposure by default

For remote deployments, implement OAuth 2.1 with PKCE per the MCP specification.

⚠️ Known Limitations

Limitation	Details	Workaround
Clone requires disk space	Each clone needs 2-4GB	Free disk space before cloning
DirectX blank screenshots	MEmu's DirectX mode produces blank images	Set `graphics_render_mode=0` (OpenGL)
ADB requires WiFi	ADB over TCP needs VM WiFi enabled	Call `connect_network()` first
Config needs stopped VM	CPU/RAM/resolution only changeable when stopped	`stop_vm()` before config changes
Windows only	MEmu is Windows-only software	No Linux/macOS support

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing)
Open a Pull Request

📝 License

This project is licensed under the MIT License — see the LICENSE file for details.

🙏 Acknowledgments

MEmu Player — Android emulator
PyMEMUC — Python MEMUC wrapper
Model Context Protocol — AI tool interoperability standard
FastMCP — Python MCP SDK

Built with ❤️ by Devbysatyam @ Avion

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
assets		assets
resources		resources
src/mcp_memu		src/mcp_memu
tools		tools
utils		utils
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
main.py		main.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
server.py		server.py

Folders and files

Latest commit

History

Repository files navigation

MCP-MEmu

AI-Powered Android Emulator Control via Model Context Protocol

🌟 What is MCP-MEmu?

✨ Features

🎮 69 Automation Tools

📚 8 MCP Resources (LLM Context)

💡 7 Prompt Templates (Guided Workflows)

🛡️ Security

🚀 Quick Start

Prerequisites

Installation

Run the Server

Connect to Claude Desktop

Connect to Antigravity / Gemini

📖 Use Cases

1. 📱 Automated App Testing

2. 🌍 GPS-Based Testing

3. 🏭 Device Farm Setup

4. 🔄 CI/CD Integration

5. 📋 Clipboard & File Transfer

6. 🔧 VM Configuration Management

🔧 Tool Reference

Lifecycle Management

Configuration

App Management

UI Interaction

Screenshot & Capture

Network & Sensors

Shell & Advanced

Compound (Multi-Step)

🏗️ Architecture

📁 Project Structure

📦 Dependencies

🔒 Security

⚠️ Known Limitations

🤝 Contributing

📝 License

🙏 Acknowledgments

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages