# Airtest MCP

A local Model Context Protocol server that lets MCP clients operate the
portable AirtestIDE runner on Android, iOS and Windows.

The project does **not** bundle AirtestIDE, ADB, WebDriverAgent or any NetEase
binaries. Download AirtestIDE separately from its official distribution and
point this server at the extracted directory.

## Tools

| Tool | Purpose |
| --- | --- |
| `airtest_info` | Show the detected AirtestIDE runtime |
| `list_android_devices` | Enumerate devices through bundled ADB |
| `run_airtest_script` | Run an existing `.air` project |
| `run_airtest_code` | Run trusted inline Airtest Python |
| `snapshot` | Capture a device screenshot |
| `touch` | Tap an absolute coordinate |
| `swipe` | Swipe between coordinates |
| `keyevent` | Send an Android-oriented key event |
| `start_app` | Start an Android package or iOS bundle ID |
| `stop_app` | Stop an Android package or iOS bundle ID |

## Requirements

- Windows 10/11
- Python 3.11 or newer
- Portable AirtestIDE extracted locally
- Android: USB debugging or network ADB
- iOS: a signed and running WebDriverAgent endpoint

## Install for Codex

```powershell
git clone https://github.com/Heand-Broken/airtest-mcp.git
cd airtest-mcp
.\scripts\install_codex.ps1 -AirtestIdeRoot "F:\AirtestIDE"
```

Restart Codex after installation. The installer creates an isolated virtual
environment, installs the package, backs up `~/.codex/config.toml`, and adds:

```toml
[mcp_servers.airtest]
command = 'C:\Users\you\.codex\mcp\airtest-mcp\.venv\Scripts\python.exe'
args = [ '-m', 'airtest_mcp' ]

[mcp_servers.airtest.env]
AIRTEST_IDE_ROOT = 'F:\AirtestIDE'
AIRTEST_MCP_RUNS_DIR = 'C:\Users\you\AppData\Local\airtest-mcp\runs'
```

Ready-to-edit service configurations are included for multiple clients:

- `config/codex.toml.example`
- `config/claude_desktop_config.json.example`
- `config/stdio-server.json.example`

See `docs/configuration.md` for installation paths, environment variables and
service verification.

## Environment variables

| Variable | Required | Purpose |
| --- | --- | --- |
| `AIRTEST_IDE_ROOT` | Yes, unless auto-detected | Directory containing `AirtestIDE.exe` |
| `AIRTEST_MCP_RUNS_DIR` | No | Directory for generated temporary `.air` projects |

Start from `.env.example` when configuring a shell or local development
environment. MCP clients should normally place these values in the server's
`env` object instead.

## Device URIs

```text
Android:///SERIAL
iOS:///http://127.0.0.1:8100
Windows:///
```

Run `list_android_devices` first, then build the Android URI from the returned
serial. iOS requires WebDriverAgent to be deployed and reachable before Airtest
can connect.

## Development

```powershell
python -m venv .venv
.\.venv\Scripts\python -m pip install -e ".[dev]"
.\.venv\Scripts\ruff check .
.\.venv\Scripts\pytest
.\.venv\Scripts\python scripts\verify_mcp.py
```

## Safety

`run_airtest_code` executes Python inside the local Airtest runner. Keep the MCP
server on stdio and only invoke code from trusted clients. Use automation only
on applications, devices and accounts you control or are authorized to test.

## License

MIT