airtest-mcp
Allows controlling Android devices through ADB, including listing devices, running Airtest scripts, capturing screenshots, tapping, swiping, sending key events, and starting or stopping apps.
Allows controlling iOS devices via a WebDriverAgent endpoint, including running Airtest scripts, capturing screenshots, tapping, swiping, and starting or stopping apps.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@airtest-mcp list connected Android devices"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Show the detected AirtestIDE runtime |
| Enumerate devices through bundled ADB |
| Run an existing |
| Run trusted inline Airtest Python |
| Capture a device screenshot |
| Tap an absolute coordinate |
| Swipe between coordinates |
| Send an Android-oriented key event |
| Start an Android package or iOS bundle ID |
| Stop an Android package or iOS bundle ID |
Related MCP server: MCP Appium Server
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
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:
[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.exampleconfig/claude_desktop_config.json.exampleconfig/stdio-server.json.example
See docs/configuration.md for installation paths, environment variables and
service verification.
Environment variables
Variable | Required | Purpose |
| Yes, unless auto-detected | Directory containing |
| No | Directory for generated temporary |
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
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
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.pySafety
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
Available Tools
10 toolsairtest_infoA
Return the detected AirtestIDE, runner and bundled ADB paths.
Inputs: no named parameters. Returns: object
keyeventC
Send an Airtest key event, primarily for Android.
Inputs: key (required), device (required). Returns: object
list_android_devicesA
List Android devices visible to the ADB bundled with AirtestIDE.
Inputs: no named parameters. Returns: object
run_airtest_codeB
Run trusted, hand-written Airtest Python code in a temporary .air project.
Inputs: code (required), device, timeout. Returns: object
run_airtest_scriptB
Run an existing .air directory with an optional Airtest device URI.
Inputs: script_path (required), device, timeout. Returns: object
snapshotB
Capture a device screenshot to an absolute local path.
Inputs: device (required), output_path (required), quality. Returns: object
start_appC
Start an Android package or iOS bundle identifier.
Inputs: device (required), package (required). Returns: object
stop_appB
Stop an Android package or iOS bundle identifier.
Inputs: device (required), package (required). Returns: object
swipeC
Swipe between two absolute screen coordinates.
Inputs: end_x (required), end_y (required), device (required), start_x (required), +3 more. Returns: object
touchC
Touch an absolute screen coordinate.
Inputs: x (required), y (required), device (required), duration. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools have clearly distinct purposes. The only potential ambiguity is between run_airtest_script and run_airtest_code, but their descriptions clarify that one runs a .air directory while the other executes inline code. No other tools overlap significantly.
All tool names use snake_case, but the pattern is mixed: some are verb_noun (list_android_devices, start_app), while others are single verbs (touch, swipe) or nouns (airtest_info, snapshot, keyevent). This inconsistency is minor, as the names are short and readable.
With 10 tools, the server is well-scoped for mobile automation. Each tool covers a core operation, and the count is appropriate for the domain without feeling sparse or overwhelming.
Core workflows are covered: device discovery, script/code execution, screenshot capture, UI interactions, and app lifecycle. Missing features like text input or screen size query can be worked around via run_airtest_code, so gaps are minor.
Related MCP Connectors
MCP server for Appcircle mobile CI/CD platform.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server that enables AI assistants to control and interact with Android devices, allowing for device management, app debugging, system analysis, and UI automation through natural language commands.8452Apache 2.0
- AlicenseCqualityCmaintenanceA Model Context Protocol (MCP) server that enables mobile app automation using Appium, supporting various device interactions, element operations, and app management through a standardized protocol.10063Apache 2.0
- AlicenseBqualityDmaintenanceA Model Context Protocol server that provides Android Debug Bridge functionality for automating Android devices, enabling remote device management, screen operations, app management, file operations, and shell command execution.209 npm1MIT
- AlicenseAqualityCmaintenanceA MCP server that enables AI assistants to control Android devices via ADB, supporting device info, screen control, input simulation, app management, shell execution, file transfer, and UI parsing.20MIT