Maamcp

🚀 MaaMCP

MaaMCP 是基於 MaaFramework 的 MCP 服務器，它為 AI 助手賦予了 Android 設備和 Windows 桌面的自動化能力，讓 AI 能夠便捷地控制設備與應用，實現各類自動化任務。

English | 中文

🚀 快速開始

安裝方式

方式一：通過 uv 安裝（推薦）

需要先安裝 uv

uvx maa-mcp

方式二：通過 pip 安裝

pip install maa-mcp

方式三：從源碼安裝

1. 克隆倉庫

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

2. 安裝 Python 依賴

pip install -e .

配置客戶端

在 Cursor 等軟件中，添加 MCP 服務器：

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

或 在 Cherry Studio 等軟件中，添加 MCP 命令：

uvx maa-mcp

✨ 主要特性

🔍 設備發現與連接

• find_adb_device_list - 掃描可用的 ADB 設備
• find_window_list - 掃描可用的 Windows 窗口
• connect_adb_device - 連接到 Android 設備
• connect_window - 連接到 Windows 窗口

👀 屏幕識別

• screencap_and_ocr - 光學字符識別（高效，推薦優先使用）
• screencap_only - 屏幕截圖，然後由大模型視覺處理（按需使用，token 開銷大）

🎮 設備控制

• click - 點擊指定座標（支持多觸點/鼠標按鍵選擇、長按）
  • Windows 上支持指定鼠標按鍵：左鍵、右鍵、中鍵
• double_click - 雙擊指定座標
• swipe - 滑動手勢（Android 設備滾動/翻頁優先使用）
• input_text - 輸入文本
• click_key - 按鍵操作（支持長按）
  • Android 上可模擬系統按鍵：返回鍵(4)、Home鍵(3)、菜單鍵(82)、音量鍵等
  • Windows 上支持虛擬按鍵碼：回車(13)、ESC(27)、方向鍵等
• keyboard_shortcut - 鍵盤快捷鍵
  • 支持組合鍵：Ctrl+C、Ctrl+V、Alt+Tab 等
• scroll - 鼠標滾輪（僅 Windows）

📝 Pipeline 生成與運行

• get_pipeline_protocol - 獲取 Pipeline 協議文檔
• save_pipeline - 保存 Pipeline JSON 到文件（支持新建和更新）
• load_pipeline - 讀取已有的 Pipeline 文件
• run_pipeline - 運行 Pipeline 並返回執行結果
• open_pipeline_in_browser - 在瀏覽器中打開 Pipeline 可視化界面

💻 使用示例

基礎用法

配置完成後，可以這樣使用： Android 自動化示例：

請用 MaaMCP 工具幫我連接 Android 設備，打開美團幫我點一份外賣，我想吃中餐，一人份，20 元左右的

Windows 自動化示例：

請用 MaaMCP 工具，看看我現在這頁 PPT 怎麼加一個旋轉特效，操作給我看下

Pipeline 生成示例：

請用 MaaMCP 工具連接我的設備，幫我打開設置，進入顯示設置，調整亮度到 50%。
操作完成後，幫我生成這個流程的 Pipeline JSON，以便後續可以直接運行。

MaaMCP 會自動：

1. 掃描可用設備/窗口
2. 建立連接
3. 自動下載並加載 OCR 資源
4. 執行識別和操作任務

高級用法

如果你希望 AI 能夠快速、高效地完成自動化任務，而不希望看到運行過程中的詳細解釋，可以將以下內容添加到你的提示詞（Prompt）中：

# Role: UI Automation Agent

## Workflow Optimization Rules
1. **Minimize Round-Trips**: 你的目標是以最少的交互次數完成任務。
2. **Critical Pattern**: 當涉及到表單/聊天輸入時，必須遵循 **[Click Focus -> Input Text -> Send Key]** 的原子化操作序列。
   - 🚫 錯誤做法：先 Click，等待結果；再 Input，等待結果；再 Press Enter。
   - ✅ 正確做法：在 `click` 之後，無需等待返回，直接在同一個 `tool_calls` 列表中根據邏輯推斷追加 `input_text` 和 `click_key`。

## Communication Style
- **NO YAPPING**: 不要複述用戶的指令，不要解釋你的步驟。
- **Direct Execution**: 接收指令 -> (內部思考) -> 直接輸出 JSON 工具調用。

性能建議

為了獲得最快的運行速度，建議使用 Flash 版本的大語言模型（如 Claude 3 Flash），這些模型在保持較高智能水平的同時，能夠顯著提升響應速度。

📚 詳細文檔

工作流程

MaaMCP 遵循簡潔的操作流程，支持多設備/多窗口協同工作：

graph LR
    A[掃描設備] --> B[建立連接]
    B --> C[執行自動化操作]

1. 掃描 - 使用 find_adb_device_list 或 find_window_list
2. 連接 - 使用 connect_adb_device 或 connect_window（可連接多個設備/窗口，獲得多個控制器 ID）
3. 操作 - 通過指定不同的控制器 ID，對多個設備/窗口執行 OCR、點擊、滑動等自動化操作

Pipeline 生成功能

MaaMCP 支持讓 AI 將執行過的操作轉換為 MaaFramework Pipeline JSON 格式，實現一次操作，無限複用。

工作原理

graph LR
    A[AI 執行操作] --> B[操作完成]
    B --> C[AI 閱讀 Pipeline 文檔]
    C --> D[AI 智能生成 Pipeline]
    D --> E[保存 JSON 文件]
    E --> F[運行驗證]
    F --> G{是否成功?}
    G -->|是| H[完成]
    G -->|否| I[分析失敗原因]
    I --> J[修改 Pipeline]
    J --> F

1. 執行操作 - AI 正常執行 OCR、點擊、滑動等自動化操作
2. 獲取文檔 - 調用 get_pipeline_protocol 獲取 Pipeline 協議規範
3. 智能生成 - AI 根據文檔規範，將有效操作轉換為 Pipeline JSON
4. 保存文件 - 調用 save_pipeline 保存生成的 Pipeline
5. 運行驗證 - 調用 run_pipeline 驗證 Pipeline 是否正常運行
6. 迭代優化 - 根據運行結果分析失敗原因，修改 Pipeline 直到成功

智能生成的優勢

與機械錄製不同，AI 智能生成具有以下優勢：

• 只保留成功路徑：如果操作過程中嘗試了多條路徑（如先進入 A 菜單沒找到，返回後又進入 B 菜單才找到），AI 會只保留最終成功的路徑，去掉失敗的嘗試
• 理解操作意圖：AI 能夠理解每個操作的目的，生成語義清晰的節點名稱
• 優化識別條件：根據 OCR 結果智能設置識別區域和匹配條件
• 驗證與迭代：通過運行驗證發現問題，自動修復並增強魯棒性

驗證與迭代優化

Pipeline 生成後，AI 會自動進行驗證和優化：

1. 運行驗證 - 執行 Pipeline 檢查是否成功
2. 失敗分析 - 如果失敗，分析具體哪個節點出錯及原因
3. 智能修復 - 常見優化手段：
   • 增加備選識別節點（在 next 列表中添加多個候選）
   • 放寬 OCR 匹配條件（使用正則表達式或部分匹配）
   • 調整 roi 識別區域
   • 增加等待時間（post_delay）
   • 添加中間狀態檢測節點
4. 重新驗證 - 修改後再次運行，直到穩定成功 如果發現 Pipeline 邏輯本身有問題，AI 還可以重新執行自動化操作，結合新舊經驗生成更完善的 Pipeline。

示例輸出

{
  "開始任務": {
    "recognition": "DirectHit",
    "action": "DoNothing",
    "next": ["點擊設置"]
  },
  "點擊設置": {
    "recognition": "OCR",
    "expected": "設置",
    "action": "Click",
    "next": ["進入顯示"]
  },
  "進入顯示": {
    "recognition": "OCR",
    "expected": "顯示",
    "action": "Click",
    "next": ["調整亮度"]
  },
  "調整亮度": {
    "recognition": "OCR",
    "expected": "亮度",
    "action": "Swipe",
    "begin": [200, 500],
    "end": [400, 500],
    "duration": 200
  }
}

🔧 技術細節

注意事項

📌 Windows 自動化限制：

• 部分遊戲或應用的反作弊機制可能會攔截後臺控制操作
• 若目標應用以管理員權限運行，MaaMCP 也需要以管理員權限啟動
• 不支持對最小化的窗口進行操作，請保持目標窗口在非最小化狀態
• 若默認的後臺截圖/輸入方式不可用（如截圖為空、操作無響應），AI 助手可能會嘗試切換到前臺方式，屆時會佔用鼠標鍵盤

常見問題

OCR 識別失敗，報錯 "Failed to load det or rec" 或提示資源不存在

首次使用時，會自動下載 OCR 模型文件。但可能出現下載失敗等情況，請檢查數據目錄：

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

1. 檢查上述目錄中是否有模型文件（det.onnx, rec.onnx, keys.txt）
2. 檢查 model/download.log 中是否出現資源下載異常
3. 手動執行 python -c "from maa_mcp.download import download_and_extract_ocr; download_and_extract_ocr()" 再次嘗試下載

關於 ISSUE

提交問題時，請提供日誌文件，日誌文件路徑如下：

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

📄 許可證

本項目採用 GNU AGPL v3 許可證。

致謝

• MaaFramework - 提供強大的自動化框架
• FastMCP - 簡化 MCP 服務器開發
• Model Context Protocol - 定義 AI 工具集成標準