Maamcp

🚀 MaaMCP

An MCP server based on MaaFramework, providing Android device and Windows desktop automation capabilities for AI assistants.

English | 中文

🚀 Quick Start

Installation Methods

Method 1: Install via uv (Recommended)

You need to install uv first.

uvx maa-mcp

Method 2: Install via pip

pip install maa-mcp

Method 3: Install from Source Code

1. Clone the repository

git clone https://github.com/MistEO/MaaMCP.git
cd MaaMCP

2. Install Python dependencies

pip install -e .

Configure the Client

In software like Cursor, add the MCP server:

{
  "mcpServers": {
    "MaaMCP": {
      "command": "maa-mcp"
    }
  }
}

Or In software like Cherry Studio, add the MCP command:

uvx maa-mcp

✨ Features

🔍 Device Discovery and Connection

• find_adb_device_list - Scan available ADB devices.
• find_window_list - Scan available Windows windows.
• connect_adb_device - Connect to an Android device.
• connect_window - Connect to a Windows window.

👀 Screen Recognition

• screencap_and_ocr - Optical Character Recognition (efficient, recommended to use first).
• screencap_only - Take a screenshot and then let the large model handle it visually (use as needed, high token cost).

🎮 Device Control

• click - Click at the specified coordinates (supports multi-touch/mouse button selection, long press).
  • On Windows, you can specify the mouse button: left, right, middle.
• double_click - Double-click at the specified coordinates.
• swipe - Swipe gesture (preferred for scrolling/turning pages on Android devices).
• input_text - Input text.
• click_key - Key press operation (supports long press).
  • On Android, you can simulate system keys: Back (4), Home (3), Menu (82), Volume keys, etc.
  • On Windows, it supports virtual key codes: Enter (13), ESC (27), Arrow keys, etc.
• keyboard_shortcut - Keyboard shortcuts.
  • Supports combination keys: Ctrl+C, Ctrl+V, Alt+Tab, etc.
• scroll - Mouse wheel (Windows only).

📝 Pipeline Generation and Execution

• get_pipeline_protocol - Get the Pipeline protocol documentation.
• save_pipeline - Save the Pipeline JSON to a file (supports creation and update).
• load_pipeline - Read an existing Pipeline file.
• run_pipeline - Run the Pipeline and return the execution result.
• open_pipeline_in_browser - Open the Pipeline visualization interface in the browser.

💻 Usage Examples

After configuration, you can use it like this:

Android Automation Example:

Please use the MaaMCP tool to connect to my Android device, open Meituan and order a takeaway for me. I want Chinese food for one person, about 20 yuan.

Windows Automation Example:

Please use the MaaMCP tool to show me how to add a rotation effect to this page of my PPT.

Pipeline Generation Example:

Please use the MaaMCP tool to connect to my device, open the settings, enter the display settings, and adjust the brightness to 50%.
After the operation is completed, help me generate the Pipeline JSON for this process so that I can run it directly later.

MaaMCP will automatically:

1. Scan available devices/windows.
2. Establish connections.
3. Automatically download and load OCR resources.
4. Perform recognition and operation tasks.

Large Model Prompts

If you want the AI to complete automation tasks quickly and efficiently without seeing detailed explanations during the operation, you can add the following content to your prompt:

# Role: UI Automation Agent

## Workflow Optimization Rules
1. **Minimize Round-Trips**: Your goal is to complete the task with the fewest interactions.
2. **Critical Pattern**: When it comes to form/chat input, you must follow the atomic operation sequence of **[Click Focus -> Input Text -> Send Key]**.
   - 🚫 Wrong approach: Click first, wait for the result; then Input, wait for the result; then Press Enter.
   - ✅ Correct approach: After `click`, without waiting for the return, directly append `input_text` and `click_key` to the same `tool_calls` list based on logical inference.

## Communication Style
- **NO YAPPING**: Don't repeat the user's instructions or explain your steps.
- **Direct Execution**: Receive the instruction -> (internal thinking) -> directly output the JSON tool call.

Performance Suggestions

To get the fastest running speed, it is recommended to use the Flash version of large language models (such as Claude 3 Flash). These models can significantly improve the response speed while maintaining a high level of intelligence.

Workflow

MaaMCP follows a simple operation process and supports multi-device/multi-window collaborative work:

graph LR
    A[Scan devices] --> B[Establish connections]
    B --> C[Perform automation operations]

1. Scan - Use find_adb_device_list or find_window_list.
2. Connect - Use connect_adb_device or connect_window (you can connect to multiple devices/windows and get multiple controller IDs).
3. Operate - Specify different controller IDs to perform automation operations such as OCR, click, and swipe on multiple devices/windows.

Pipeline Generation Function

MaaMCP supports letting AI convert executed operations into MaaFramework Pipeline JSON format, achieving one operation, infinite reuse.

Working Principle

graph LR
    A[AI performs operations] --> B[Operations completed]
    B --> C[AI reads Pipeline documentation]
    C --> D[AI intelligently generates Pipeline]
    D --> E[Save JSON file]
    E --> F[Run verification]
    F --> G{Is it successful?}
    G -->|Yes| H[Completed]
    G -->|No| I[Analyze the failure reason]
    I --> J[Modify the Pipeline]
    J --> F

1. Perform operations - AI normally performs automation operations such as OCR, click, and swipe.
2. Get documentation - Call get_pipeline_protocol to get the Pipeline protocol specification.
3. Intelligent generation - AI converts effective operations into Pipeline JSON according to the documentation specification.
4. Save the file - Call save_pipeline to save the generated Pipeline.
5. Run verification - Call run_pipeline to verify whether the Pipeline runs normally.
6. Iterative optimization - Analyze the failure reason based on the running result and modify the Pipeline until it succeeds.

Advantages of Intelligent Generation

Compared with mechanical recording, AI intelligent generation has the following advantages:

• Only keep the successful path: If multiple paths are tried during the operation (e.g., enter Menu A first but don't find it, then return and enter Menu B to find it), AI will only keep the final successful path and remove failed attempts.
• Understand operation intentions: AI can understand the purpose of each operation and generate semantically clear node names.
• Optimize recognition conditions: Intelligently set the recognition area and matching conditions according to the OCR result.
• Verification and iteration: Discover problems through running verification, automatically fix them, and enhance robustness.

Verification and Iterative Optimization

After the Pipeline is generated, AI will automatically perform verification and optimization:

1. Run verification - Execute the Pipeline to check if it succeeds.
2. Failure analysis - If it fails, analyze which specific node has an error and the reason.
3. Intelligent repair - Common optimization methods:
   • Add alternative recognition nodes (add multiple candidates to the next list).
   • Relax OCR matching conditions (use regular expressions or partial matching).
   • Adjust the roi recognition area.
   • Increase the waiting time (post_delay).
   • Add intermediate state detection nodes.
4. Re-verify - Run it again after modification until it succeeds stably.

If there is a problem with the Pipeline logic itself, AI can also re-execute the automation operations and generate a more complete Pipeline by combining old and new experiences.

Example Output

{
  "Start Task": {
    "recognition": "DirectHit",
    "action": "DoNothing",
    "next": ["Click Settings"]
  },
  "Click Settings": {
    "recognition": "OCR",
    "expected": "Settings",
    "action": "Click",
    "next": ["Enter Display"]
  },
  "Enter Display": {
    "recognition": "OCR",
    "expected": "Display",
    "action": "Click",
    "next": ["Adjust Brightness"]
  },
  "Adjust Brightness": {
    "recognition": "OCR",
    "expected": "Brightness",
    "action": "Swipe",
    "begin": [200, 500],
    "end": [400, 500],
    "duration": 200
  }
}

📄 Notes

📌 Windows Automation Limitations:

• The anti-cheat mechanisms of some games or applications may block background control operations.
• If the target application runs with administrator privileges, MaaMCP also needs to be started with administrator privileges.
• It does not support operations on minimized windows. Please keep the target window in a non-minimized state.
• If the default background screenshot/input method is unavailable (e.g., the screenshot is empty or the operation has no response), the AI assistant may try to switch to the foreground method, which will occupy the mouse and keyboard at that time.

📚 Documentation

OCR Recognition Fails, Reporting "Failed to load det or rec" or Prompting that Resources Do Not Exist

When using it for the first time, the OCR model files will be automatically downloaded. However, download failures may occur. Please check the data directory:

• Windows: C:\Users\<Username>\AppData\Local\MaaXYZ\MaaMCP\resource\model\ocr\
• macOS: ~/Library/Application Support/MaaMCP/resource/model/ocr/
• Linux: ~/.local/share/MaaMCP/resource/model/ocr/

1. Check if there are model files (det.onnx, rec.onnx, keys.txt) in the above directory.
2. Check if there are any resource download exceptions in model/download.log.
3. Manually execute python -c "from maa_mcp.download import download_and_extract_ocr; download_and_extract_ocr()" to try downloading again.

About ISSUE

When submitting an issue, please provide the log file. The log file path is as follows:

• Windows: C:\Users\<Username>\AppData\Local\MaaXYZ\MaaMCP\debug\maa.log
• macOS: ~/Library/Application Support/MaaXYZ/MaaMCP/debug/maa.log
• Linux: ~/.local/share/MaaXYZ/MaaMCP/debug/maa.log

📄 License

This project is licensed under the GNU AGPL v3 license.

Acknowledgments

• MaaFramework - Provides a powerful automation framework.
• FastMCP - Simplifies MCP server development.
• Model Context Protocol - Defines the AI tool integration standard.