MaaMCP

<!-- markdownlint-disable MD033 MD041 MD024 --> <p align="center"> <img alt="LOGO" src="https://cdn.jsdelivr.net/gh/MaaAssistantArknights/design@main/logo/maa-logo_512x512.png" width="256" height="256" /> </p> <div align="center"> # MaaMCP    [](https://github.com/MaaXYZ/MaaFramework) [](https://pypi.org/project/maa-mcp/) MCP Server based on [MaaFramework](https://github.com/MaaXYZ/MaaFramework) Provides automation capabilities for Android devices and Windows desktops for AI assistants [English](README_EN.md) | 中文 </div> --- ## Introduction MaaMCP is an MCP server that exposes the powerful automation capabilities of MaaFramework through a standardized MCP interface to AI assistants (such as Claude). With this server, AI assistants can: - 🤖 **Android Automation** - Connect to and control Android devices/emulators via ADB - 🖥️ **Windows Automation** - Control Windows desktop applications - 🎯 **Background Operations** - Screenshots and controls on Windows run in the background, freeing up the mouse and keyboard, allowing you to continue using your computer for other tasks - 🔗 **Multi-Device Collaboration** - Control multiple devices/windows simultaneously for cross-device automation - 👁️ **Intelligent Recognition** - Use OCR (Optical Character Recognition) to identify text content on the screen - 🎯 **Precise Operations** - Perform clicks, swipes, text input, key presses, and other actions - 📸 **Screenshots** - Capture real-time screenshots for visual analysis Talk is cheap, please see: **[🎞️ Bilibili Video Demonstration](https://www.bilibili.com/video/BV1eGmhBaEZz/)** ## Features ### 🔍 Device Discovery and Connection - `find_adb_device_list` - Scan for available ADB devices - `find_window_list` - Scan for available Windows windows - `connect_adb_device` - Connect to an Android device - `connect_window` - Connect to a Windows window ### 👀 Screen Recognition - `ocr` - Optical Character Recognition (efficient, recommended for priority use) - `screencap` - Screen Capture (use as needed, high token cost) ### 🎮 Device Control - `click` - Click at the specified coordinates (supports multi-touch/mouse button selection, long press) - On Windows, it supports specifying mouse buttons: left button, right button, middle button - `double_click` - Double-click at the specified coordinates - `swipe` - Swipe gesture - `input_text` - Input text - `click_key` - Key operation (supports long press) - On Android, it can simulate system keys: Back key (4), Home key (3), Menu key (82), Volume keys, etc. - On Windows, it supports virtual key codes: Enter (13), ESC (27), arrow keys, etc. - `keyboard_shortcut` - Keyboard shortcuts - Supports combinations: Ctrl+C, Ctrl+V, Alt+Tab, etc. - `scroll` - Mouse wheel (Windows only) ## Quick Start ### Installation Method #### Method 1: Install via pip (Recommended) ```bash pip install maa-mcp ``` #### Method 2: Install from Source 1. **Clone the Repository** ```bash git clone https://github.com/MistEO/MaaMCP.git cd MaaMCP ``` 2. **Install Python Dependencies** ```bash pip install -e . ``` ### Configure MCP Client Add MCP configuration: ```json { "mcpServers": { "MaaMCP": { "command": "maa-mcp" } } } ``` ## Usage Example After the configuration is complete, you can use it like this: **Android Automation Example:** ```text Please use the MaaMCP tool to help me connect to the Android device, open Meituan, and order a takeout. I want Chinese food, one serving, around 20 yuan. ``` **Windows Automation Example:** ```text Please use the MaaMCP tool to show me how to add a rotation effect to this PPT slide. Demonstrate the operation for me. ``` MaaMCP will automatically: 1. Scan for available devices/windows 2. Establish a connection 3. Automatically download and load OCR (Optical Character Recognition) resources 4. Execute recognition and operation tasks ## Workflow MaaMCP follows a concise operational workflow, supporting multi-device/multi-window collaborative work: ```mermaid graph LR A[Scan Devices] --> B[Establish Connection] B --> C[Execute Automation Operations] ``` 1. **Scan** - Use `find_adb_device_list` or `find_window_list` 2. **Connect** - Use `connect_adb_device` or `connect_window` (can connect to multiple devices/windows, obtaining multiple controller IDs) 3. **Operate** - Perform automation operations such as OCR, clicks, and swipes on multiple devices/windows by specifying different controller IDs ## Notes 📌 **Windows Automation Limitations**: - Some games or applications' anti-cheat mechanisms may intercept background control operations. - If the target application runs with administrator privileges, MaaMCP must also be launched with administrator privileges. - Operations on minimized windows are not supported; please keep the target window in a non-minimized state. - If the default background screenshot/input method is unavailable (e.g., screenshots are empty, operations are unresponsive), the AI assistant may attempt to switch to foreground mode, which will take control of the mouse and keyboard. ## Frequently Asked Questions ### OCR Recognition Failure, Error "Failed to load det or rec" or Resource Not Found When using for the first time, the OCR model files will be automatically downloaded. However, there may be cases of download failure, so please check the data directory: - Windows: `C:\Users\<username>\AppData\Local\MaaMCP\resource\model\ocr\` - macOS: `~/Library/Application Support/MaaMCP/resource/model/ocr/` - Linux: `~/.local/share/MaaMCP/resource/model/ocr/` 1. Check if the model files (`det.onnx`, `rec.onnx`, `keys.txt`) are present in the above directories. 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 attempt the download 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\MaaMCP\debug\maa.log` - macOS: `~/Library/Application Support/MaaMCP/debug/maa.log` - Linux: `~/.local/share/MaaMCP/debug/maa.log` ## License This project is licensed under the [GNU AGPL v3](LICENSE) license. ## Acknowledgments - **[MaaFramework](https://github.com/MaaXYZ/MaaFramework)** - Provides a powerful automation framework - **[FastMCP](https://github.com/jlowin/fastmcp)** - Simplifies MCP Server development - **[Model Context Protocol](https://modelcontextprotocol.io/)** - Defines standards for AI tool integration