MCP Android-агент

Этот проект предоставляет сервер MCP (Model Context Protocol) для автоматизации устройств Android с использованием uiautomator2 . Он разработан для легкого подключения к агентам ИИ, таким как GitHub Copilot Chat, Claude или Open Interpreter, для управления устройствами Android с помощью естественного языка.

Быстрая демонстрация

Требования

Python 3.13 или выше
Android Debug Bridge (adb) установлен и находится в PATH
Подключенное Android-устройство с включенной отладкой по USB
Android-устройство, совместимое с uiautomator2

Функции

Запуск, остановка и управление приложениями по имени пакета
Извлечь установленные приложения и текущее активное приложение
Нажимайте, проводите пальцем, прокручивайте, перетаскивайте и выполняйте взаимодействия с пользовательским интерфейсом.
Получите информацию об устройстве, разрешении экрана, состоянии батареи и многом другом.
Делайте снимки экрана или последние всплывающие сообщения
Программная разблокировка, вывод из спящего режима или включение экрана
Очистите данные приложения и дождитесь действий
Включает проверку работоспособности и диагностический инструмент adb

Варианты использования

Идеально подходит для:

Агенты ИИ, которым необходимо взаимодействовать с реальными устройствами
Настройки удаленного управления устройством
Автоматизированные инструменты контроля качества
Фреймворки Android-ботов
Тестирование и автоматизация пользовательского интерфейса
Управление устройствами и мониторинг

Установка

1. Клонировать репозиторий

git clone https://github.com/nim444/mcp-android.git
cd mcp-android

2. Создать и активировать виртуальную среду

# Using uv (https://github.com/astral-sh/uv)
uv venv
source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate

3. Установка зависимостей

uv pip install

Запуск сервера

Вариант 1: Использование uvicorn (рекомендуется)

uvicorn server:app --factory --host 0.0.0.0 --port 8000

Вариант 2: Использование MCP stdio (для интеграции агента ИИ)

python server.py

Использование

Для использования этого сервера необходим клиент MCP. Приложение Claude Desktop является примером клиента MCP. Для использования этого сервера с Claude Desktop:

Найдите файл конфигурации Claude Desktop.

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Добавьте конфигурацию сервера Android MCP в раздел mcpServers.

{
  "mcpServers": {
    "mcp-android": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"
      ]
    }
  }
}

Замените /path/to/mcp-adb на абсолютный путь к месту, где вы клонировали этот репозиторий. Например: /Users/username/Projects/mcp-adb

Использование с VS Code

Вы также можете использовать этот сервер MCP с режимом агента VS Code (требуется VS Code 1.99 или более новая версия). Для настройки:

Создайте файл .vscode/mcp.json в своей рабочей области:

{
  "servers": {
    "mcp-android": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"
      ]
    }
  }
}

Замените /path/to/mcp-adb на абсолютный путь к месту, куда вы клонировали этот репозиторий.

После добавления конфигурации вы сможете управлять сервером с помощью:

Палитра команд → MCP: List Servers для просмотра и управления настроенными серверами
Палитра команд → MCP: Start Server для запуска сервера.
Инструменты сервера будут доступны в чате агентского режима VS Code.

Инспектор пользовательского интерфейса

Проект включает поддержку uiauto.dev — мощного инструмента проверки пользовательского интерфейса для просмотра и анализа структуры интерфейса вашего устройства.

Установите инспектор пользовательского интерфейса:

uv pip install uiautodev

Запустите инспектор:

uiauto.dev

Откройте браузер и перейдите на https://uiauto.dev

Доступные инструменты MCP

Название инструмента	Описание
`mcp_health`	Проверьте, правильно ли работает сервер MCP.
`connect_device`	Подключитесь к устройству Android и получите основную информацию
`get_installed_apps`	Список всех установленных приложений с информацией о версии и пакете
`get_current_app`	Получить информацию о приложении, которое в данный момент находится на переднем плане
`start_app`	Запустите приложение по имени пакета
`stop_app`	Остановить приложение по имени пакета
`stop_all_apps`	Остановите все запущенные приложения.
`screen_on`	Включить экран
`screen_off`	Выключить экран
`get_device_info`	Получите подробную информацию об устройстве: серийный номер, разрешение, аккумулятор и т. д.
`press_key`	Имитировать нажатие аппаратных клавиш (например, `home` , `back` , `menu` и т. д.)
`unlock_screen`	Разблокируйте экран (включите и проведите пальцем по экрану, если необходимо)
`check_adb`	Проверьте, установлен ли ADB, и выведите список подключенных устройств.
`wait_for_screen_on`	Асинхронно ждать, пока экран включится
`click`	Нажмите на элемент по `text` , `resourceId` или `description`
`long_click`	Выполнить долгий щелчок по элементу
`send_text`	Введите текст в текущее поле с фокусом (возможно, с очисткой перед этим)
`get_element_info`	Получите информацию об элементах пользовательского интерфейса (текст, границы, кликабельность и т. д.)
`swipe`	Проведите пальцем от одной координаты к другой
`wait_for_element`	Дождитесь появления элемента на экране.
`screenshot`	Сделайте и сохраните снимок экрана с устройства.
`scroll_to`	Прокручивайте, пока нужный элемент не станет видимым.
`drag`	Перетащите элемент в определенное место на экране.
`get_toast`	Получить последнее всплывающее сообщение, показанное на экране
`clear_app_data`	Очистить пользовательские данные/кэш указанного приложения
`wait_activity`	Подождите, пока не появится определенное действие
`dump_hierarchy`	Вывести иерархию пользовательского интерфейса текущего экрана в формате XML

Лицензия

Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE .

MCP Android Agent

Integrations