Codex Android MCP

简体中文

Локально-ориентированный MCP-сервер, который позволяет Codex проверять, тестировать и управлять Android-эмуляторами через adb. Он предоставляет строгие типизированные инструменты через STDIO, возвращает скриншоты как нативные MCP-изображения и держит физические устройства и выполнение Gradle за явной политикой запуска.

Это независимый общественный проект. Он не связан с OpenAI, DeepSeek или Google и не одобрен ими. Android-реализация основана на ZSeven-W/dsh-android в соответствии с лицензией MIT; регистрация DSH/Cordis и веб-панель заменены на официальный MCP TypeScript SDK.

Что изменилось по сравнению с dsh-android

• Нативный MCP STDIO-сервер для Codex Desktop, CLI и IDE.

• Совместимость с протоколом MCP эпохи 2026 и устаревшим протоколом 2025 через serveStdio.

• Скриншоты возвращаются как ImageContent; приватные временные PNG-файлы удаляются после кодирования.

• По умолчанию работа только с эмуляторами. Физические устройства требуют двух явных согласий при запуске и их точного серийного номера при каждом вызове.

• android_build_run по умолчанию отсутствует. Его включение также требует канонических доверенных корней проектов.

• Строгие JSON-схемы, валидация пакетов/серийных номеров/путей, ограниченные выходные данные, фильтрация журналов по точным литералам, отмена запросов и консервативные аннотации инструментов.

• Никакого «сырого» adb, шелла, произвольных команд, HTTP или живого сайдбара DSH.

Related MCP server: adb-mcp-server

Требования

• Node.js 20.11 или новее.

• Android SDK Platform-Tools (adb). Установите их через SDK Manager в Android Studio или через пакет Platform-Tools.

• Настоятельно рекомендуется использовать одноразовый Android-эмулятор.

• Лаунчер Android-эмулятора необязателен и требуется только тогда, когда android_boot получает имя AVD.

• OCR-инструменты в настоящее время требуют macOS и Apple Vision. Все инструменты, не связанные с OCR, кроссплатформенны; сборка/запуск — явное согласие (opt-in).

Ни adb, ни бинарный файл эмулятора не поставляются и не загружаются.

Установка для Codex

git clone https://github.com/zifanersuotang/codex-android-mcp.git
cd codex-android-mcp
npm ci
npm run build
codex mcp add android -- node C:/absolute/path/to/codex-android-mcp/lib/index.js

Codex Desktop и CLI используют общую конфигурацию MCP. Эквивалентная явная конфигурация:

[mcp_servers.android]
command = "node"
args = ["C:/absolute/path/to/codex-android-mcp/lib/index.js"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "writes"

[mcp_servers.android.env]
ANDROID_MCP_ALLOWED_SERIALS = "emulator-5554"

Перезапустите Codex после изменения конфигурации. Попросите Codex «перечислить Android-устройства», чтобы проверить соединение. Оставляйте включённым подтверждение для инструментов записи; аннотации MCP — это лишь подсказки по использованию, а не граница авторизации.

Политика безопасности

Безопасная конфигурация по умолчанию открывает 19 инструментов и разрешает только стандартные локальные цели emulator-<port>. Сетевые и сторонние серийные номера эмуляторов подчиняются политике физических устройств. При каждом вызове цель заново обнаруживается и авторизуется непосредственно перед выполнением; неавторизованные физические/сетевые устройства исключаются из android_devices.

| Переменная окружения | По умолчанию | Эффект |---|---|---|---| | ----------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | ANDROID_MCP_ALLOWED_SERIALS | пусто | Необязательный точный список разрешённых серийных номеров подключённых устройств через запятую. Физический серийный номер должен присутствовать здесь. | | ANDROID_MCP_ALLOWED_AVDS | пусто | Необязательный точный список имён AVD через запятую, принимаемых инструментом android_boot. | | ANDROID_MCP_ALLOW_PHYSICAL | false | Включает учёт физических устройств, но только если их точный серийный номер также внесён в список разрешений и передан при каждом вызове. | | ANDROID_MCP_ALLOWED_PACKAGES | пусто | Необязательный список разрешённых пакетов через запятую для инструментов, работающих с пакетами. Отключает запуск по одному имени и трассировку только по PID. | | ANDROID_MCP_ALLOW_BUILD_RUN | false | Открывает android_build_run. Самого по себе этого недостаточно. | | ANDROID_MCP_ALLOWED_PROJECT_ROOTS | пусто | Обязательные корни сборки, разделённые ; в Windows и : в macOS/Linux. projectPath должен напрямую содержать настройки Gradle и Wrapper, не являющийся симлинком. | | ANDROID_MCP_CACHE_DIR | Временная папка ОС | Приватная временная рабочая папка. Файлы скриншотов удаляются после кодирования в MCP-изображение. | | ANDROID_MCP_MAX_IMAGE_BYTES | 8388608 | Максимальный размер PNG-скриншота в байтах, возвращаемый клиенту. | | ANDROID_MCP_MAX_TEXT_BYTES | 4096 | Максимальный текстовый объём, принимаемый инструментом android_interact. |

Пример использования с физическим устройством — для отдельного тестового телефона:

[mcp_servers.android.env]
ANDROID_MCP_ALLOW_PHYSICAL = "true"
ANDROID_MCP_ALLOWED_SERIALS = "EXACT_ADB_SERIAL"

Не используйте этот профиль с личным телефоном или личными учётными записями. Авторизация отладки по USB означает, что телефон доверяет хост-машине; она не авторизует действия модели.

Пример сборки/запуска для одного доверенного проекта:

[mcp_servers.android.env]
ANDROID_MCP_ALLOW_BUILD_RUN = "true"
ANDROID_MCP_ALLOWED_PROJECT_ROOTS = "C:/work/MyTrustedApp"
ANDROID_MCP_ALLOWED_SERIALS = "emulator-5554"

Настройки Gradle и сценарии сборки выполняют код на хост-машине. Список разрешённых путей — это не песочница: включайте это только для кода, которому доверяете, а для недостоверных проектов используйте виртуальную машину или контейнер без учётных данных.

Прежде чем включать физические устройства или сборку/запуск, ознакомьтесь с разделом Модель безопасности и Политикой безопасности.

Инструменты

Экраны, UI-деревья, OCR-данные, логи, имена приложений и файлы на устройстве — это ненадёжные данные. Никогда нельзя разрешать содержимому устройства выдавать разрешения или направить Codex на вызов другого инструмента. Не вводите через этот сервер пароли, одноразовые коды, платёжные данные, личные сообщения или подтверждения удаления аккаунтов.

Типовой сценарий

1. android_devices

2. android_screenshot или android_ui_tree

3. Определите точную цель; остановитесь, если она неоднозначна.

4. Используйте один инструмент взаимодействия с подтверждением.

5. Проверьте полученный скриншот или журналы перед следующим действием.

MCP не воспроизводит постоянный живой сайдбар dsh-android. android_boot инициализирует внутренний источник кадров для сопоставления координат; вызывайте android_screenshot всякий раз, когда Codex или пользователю нужно увидеть экран.

Развитие

npm ci
npm run typecheck
npm test
npm pack --dry-run

Тестовый пакет включает модульные тесты политики, реальный запускаемый STDIO-клиент в устаревшем и современном режимах протокола, прямой проход тестирования MCP-изображения в памяти, дымовых тестов с фейковым adb, тесты ограничений журналов, фикстуры UI-дерева и проверки деградации OCR. npm run test:device — опциональная команда и должна запускаться только на эмуляторе одноразового времени.

Лицензия и атрибуция

MIT. Источник: dsh-android. Оригинальные авторские права и лицензия dsh-android сохранены в LICENSE, подробная история — в THIRD_PARTY_NOTICES.md.