MaaMCP

MaaMCP — это MCP-сервер, который предоставляет AI-ассистентам (например, Claude) возможность автоматизации Android-устройств и Windows-приложений через стандартизированный протокол MCP. Сервер построен на базе фреймворка MaaFramework.

Возможности

• Android-автоматизация — управление Android-устройствами и эмуляторами через ADB.
• Windows-автоматизация — управление окнами приложений в фоне, не блокируя мышь и клавиатуру.
• Мультиустройственность — одновременная работа с несколькими устройствами или окнами.
• OCR — распознавание текста на экране.
• Точные действия — клики, свайпы, ввод текста, нажатие клавиш, скриншоты.
• Фоновые операции — на Windows скриншоты и управление выполняются без захвата ввода.

Установка

Через pip (рекомендуется)

pip install maa-mcp

Из исходного кода

git clone https://github.com/MistEO/MaaMCP.git
cd MaaMCP
pip install -e .

Настройка клиента

Добавьте MCP-сервер в вашем клиенте (Cursor, Cherry Studio и т.п.):

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

Или укажите команду maa-mcp в настройках MCP.

Быстрый старт

После настройки AI-ассистент сможет выполнять задачи, например:

• Android: «Подключись к Android-устройству, открой приложение и сделай скриншот».
• Windows: «Найди окно браузера, кликни по адресной строке и введи URL».

Сервер автоматически:

1. Сканирует доступные устройства/окна.
2. Устанавливает соединение.
3. Загружает OCR-модели (при первом запуске).
4. Выполняет команды.

Рабочий процесс

1. Сканирование — find_adb_device_list (Android) или find_window_list (Windows).
2. Подключение — connect_adb_device или connect_window. Можно подключить несколько устройств/окон, каждое получает свой controller_id.
3. Действия — используйте controller_id для выполнения операций: OCR, клики, свайпы, ввод текста и т.д.

Основные инструменты

Управление устройствами

• find_adb_device_list — поиск Android-устройств.
• find_window_list — поиск окон Windows.
• connect_adb_device — подключение к Android.
• connect_window — подключение к окну Windows.

Распознавание

• ocr — оптическое распознавание текста (рекомендуется).
• screencap — скриншот экрана (используйте при необходимости, высокий расход токенов).

Действия

• click — клик по координатам (поддерживает мультитач, выбор кнопки мыши, долгое нажатие).
• double_click — двойной клик.
• swipe — свайп (для Android-скролла).
• input_text — ввод текста.
• click_key — нажатие клавиши (Android: системные кнопки, Windows: виртуальные коды).
• keyboard_shortcut — комбинации клавиш (Ctrl+C, Alt+Tab и т.д.).
• scroll — прокрутка колесом мыши (только Windows).

Важные замечания

• Windows: некоторые приложения с античитом могут блокировать фоновое управление. Если целевое приложение запущено от администратора, MaaMCP тоже нужно запускать с правами администратора. Не поддерживаются свёрнутые окна.

• OCR: при первом запуске автоматически загружаются модели. Если загрузка не удалась, проверьте папку:

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

  Убедитесь, что там есть файлы det.onnx, rec.onnx, keys.txt. При ошибках смотрите model/download.log.

Решение проблем

При возникновении ошибок приложите лог-файл:

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

Лицензия

Проект распространяется под лицензией GNU AGPL v3. Подробнее — в файле LICENSE.

Благодарности

• MaaFramework — основа автоматизации.
• FastMCP — упрощение разработки MCP-сервера.
• Model Context Protocol — стандарт интеграции AI-инструментов.