Skip to main content
Glama

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

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

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

Available Tools

10 tools
airtest_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

    B3.4/5.0

    Scored across 10 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      8
      452
      Apache 2.0
    • A
      license
      B
      quality
      D
      maintenance
      A 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.
      20
      9 npm
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      A 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.
      20
      MIT