# mcp-mumu (macOS 适配版)

MCP Server for controlling Netease **MuMu Player 12** Android emulator — patched to work on **macOS**.

> Fork/adaptation of [nnaridz/mcp-mumu](https://github.com/nnaridz/mcp-mumu) (Windows-only).
> 本仓库在原版基础上增加了 macOS 支持，其余功能与原版一致（59 个工具）。

## What's changed for macOS

The upstream project hardcodes Windows-only paths (`mumu-cli.exe`, `C:\Program Files\...`).
This fork adds platform detection and adapts to the macOS MuMu Player layout:

| Component | Windows (upstream) | macOS (this fork) |
|---|---|---|
| Detection | `C:\Program Files\Netease\MuMuPlayer\nx_main` | `/Applications/MuMuPlayer.app/Contents/MacOS` |
| CLI binary | `mumu-cli.exe` | `mumu-cli` |
| adb | `adb.exe` (same dir) | `MuMuEmulator.app/Contents/MacOS/tools/adb` |
| List instances | `info --vmindex all` | `info all` |
| Start / Stop / Reboot | `control --vmindex N launch/shutdown/restart` | `open N` / `close N` / `restart N` |
| Create / Clone / Delete | `--vmindex` / `--number` | positional device index, `--count` |
| App install/launch/etc. | `control N app install --apk X` | `control N --action install_apk --path X` |
| App list | `control N app info --installed` | `pm list packages -3` via adb |
| Text input | `mumu-cli adb --cmd input_text` | `input text` via adb shell |

Not supported on macOS: `rename` (no such subcommand in macOS mumu-cli).
Settings get/set fall back gracefully with error info if syntax differs.

## Requirements

- macOS with [MuMu Player 12 for Mac](https://mumu.163.com/mac/) installed at `/Applications/MuMuPlayer.app`
- Python >= 3.10
- The MCP SDK v1 API (`mcp>=1.0.0,<2`)

## Install

```bash
git clone https://github.com/mohdkey/mcp-mumu.git
cd mcp-mumu
python3 -m venv ~/.venvs/mcp-mumu
~/.venvs/mcp-mumu/bin/pip install "mcp>=1.0.0,<2" -e .
```

## MCP client configuration

```json
{
  "mcp": {
    "servers": {
      "mcp-mumu": {
        "command": "/Users/YOU/.venvs/mcp-mumu/bin/python3",
        "args": ["-m", "mcp_mumu.server"]
      }
    }
  }
}
```

- ZCode: `~/.zcode/cli/config.json` -> `mcp.servers`
- Claude Desktop: `claude_desktop_config.json` -> `mcpServers` (same shape, without the outer `mcp` wrapper)

## Tools (59)

- Lifecycle: `create / clone / delete / list / start / stop / reboot / boot_ready / import / export`
- Apps: `install / batch_install / uninstall / launch / close / fresh_start / list / info / clear_data`
- UI automation: `tap / swipe / long_press / text_input / key_event / home / back / recent / scroll / rotate`
- Screen: `screenshot (file & base64) / screen_size`
- Device: `gps / airplane_mode / wifi / volume / shake / network_info / public_ip`
- ADB: `shell command execution` on the emulator

## Quick check

```bash
~/.venvs/mcp-mumu/bin/python3 -m mcp_mumu.server --list-tools
```

## Credits

- Upstream: [nnaridz/mcp-mumu](https://github.com/nnaridz/mcp-mumu)
- Emulator: [Netease MuMu Player 12](https://mumu.163.com/)