MaaMCP Server

Exposes MaaFramework automation via MCP to automate Android devices and Windows apps with OCR, screen capture, and multi-device coordination.

python

275

GitHub Stars

python

Language

5 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "maa-ai-maamcp": {
      "command": "uvx",
      "args": [
        "maa-mcp"
      ]
    }
  }
}

MaaMCP is an MCP server that exposes MaaFramework’s powerful automation capabilities through a standardized MCP interface, enabling an AI assistant to automate Android devices and Windows desktop apps with multi-device orchestration, OCR-based recognition, and real-time screen capture.

How to use

Connect MaaMCP to your MCP client to begin automating tasks across devices and windows. You can discover available Android devices and Windows windows, establish connections, and then issue automation commands such as OCR, clicking, swiping, text input, and keyboard shortcuts. You can also generate and run Pipelines to encapsulate repetitive actions for future reuse. The workflow supports coordinating multiple devices or windows in parallel, making it suitable for cross-device automation and complex scenarios.

How to install

Choose one of the installation methods below and run the commands in your terminal.

# Option 1: Install via uvx (recommended)
uvx maa-mcp

# Option 2: Install via Python's pip
pip install maa-mcp

# Option 3: Install from source
# 1) Clone the repository
git clone https://github.com/MistEO/MaaMCP.git
cd MaaMCP

# 2) Install Python dependencies in editable mode
pip install -e .

Additional setup notes

After installing MaaMCP, you will set up MCP servers in your client configuration. Use the standard MCP server entry to point your client to MaaMCP so you can start discovering devices, establishing connections, and running automation tasks.

Available tools

find_adb_device_list

Scans for available Android devices connected via ADB and returns a list of device identifiers.

find_window_list

Scans for available Windows windows and returns a list of window handles and titles.

connect_adb_device

Establishes a connection to a selected Android device for subsequent automation tasks.

connect_window

Connects to a specific Windows window to enable control and OCR-based interaction.

screencap_and_ocr

Captures the screen and performs optical character recognition to extract text for decision making.

screencap_only

Captures the screen for later processing by an external model or workflow.

click

Performs a tap/click at given coordinates, with options for multi-point and long-press actions.

double_click

Performs a double-click at specified coordinates.

swipe

Executes a swipe gesture to scroll or flip pages on Android devices.

input_text

Inputs text into the focused element, with support for long-press if needed.

click_key

Simulates a key press or a long press of a key, including Android system keys and Windows virtual keys.

keyboard_shortcut

Performs keyboard shortcuts such as Ctrl+C, Ctrl+V, Alt+Tab and other combinations.

scroll

Scrolls the mouse wheel on Windows.

get_pipeline_protocol

Retrieves the documentation for the Pipeline JSON protocol.

save_pipeline

Saves a Pipeline JSON to a file, supporting create and update flows.

load_pipeline

Loads an existing Pipeline JSON from a file.

run_pipeline

Executes a saved Pipeline and returns execution results.

open_pipeline_in_browser

Opens the Pipeline visualization interface in a web browser.