Codex Android MCP

简体中文

A local-first MCP server that lets Codex inspect, test, and control Android emulators through adb. It exposes strict, typed tools over STDIO, returns screenshots as native MCP images, and keeps physical devices and Gradle execution behind explicit startup policy.

This is an independent community project. It is not affiliated with or endorsed by OpenAI, DeepSeek, or Google. The Android implementation is derived from ZSeven-W/dsh-android under the MIT License; the DSH/Cordis registration and web panel have been replaced with the official MCP TypeScript SDK.

What changed from dsh-android

• Native MCP STDIO server for Codex Desktop, CLI, and IDE clients.
• 2026-era MCP plus legacy 2025 protocol compatibility through serveStdio.
• Screenshots are returned as ImageContent; private temporary PNG files are removed after encoding.
• Emulator-only default. Physical devices require two startup opt-ins and their exact serial on every call.
• android_build_run is absent by default. Enabling it also requires canonical trusted project roots.
• Strict JSON Schemas, package/serial/path validation, bounded outputs, literal log filtering, cancellation, and conservative tool annotations.
• No raw adb, shell, arbitrary command, HTTP, or live DSH sidebar surface.

Requirements

• Node.js 20.11 or newer.
• Android SDK Platform-Tools (adb). Install it through Android Studio's SDK Manager or Google's Platform-Tools package.
• A disposable Android emulator is strongly recommended.
• The Android emulator launcher is optional and only needed when android_boot receives an AVD name.
• OCR tools currently require macOS and Apple Vision. All non-OCR tools are cross-platform; build/run is an explicit opt-in.

Neither adb nor an emulator binary is bundled or downloaded.

Install for 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 and the CLI share MCP configuration. An equivalent explicit configuration is:

[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"

Restart Codex after changing the configuration. Ask Codex to “list the Android devices” to verify the connection. Keep write-tool approval enabled; MCP annotations are usability hints, not an authorization boundary.

Security policy

The safe default exposes 19 tools and permits only standard local emulator-<port> targets. Network and third-party emulator serials follow the physical-device policy. Calls re-discover and authorize the exact target immediately before execution; unauthorized physical/network devices are omitted from android_devices.

Environment variable	Default	Effect
ANDROID_MCP_ALLOWED_SERIALS	empty	Optional comma-separated exact allowlist for connected devices. A physical serial must be present here.
ANDROID_MCP_ALLOWED_AVDS	empty	Optional comma-separated exact allowlist for AVD names accepted by android_boot.
ANDROID_MCP_ALLOW_PHYSICAL	false	Enables consideration of physical devices, but only when their exact serial is also allowlisted and supplied on every call.
ANDROID_MCP_ALLOWED_PACKAGES	empty	Optional comma-separated package allowlist for package-targeted tools. Disables name-only launch and PID-only backtrace.
ANDROID_MCP_ALLOW_BUILD_RUN	false	Exposes android_build_run. This is not sufficient by itself.
ANDROID_MCP_ALLOWED_PROJECT_ROOTS	empty	Required build roots, separated by ; on Windows and : on macOS/Linux. projectPath must directly contain Gradle settings and a non-symlink Wrapper.
ANDROID_MCP_CACHE_DIR	OS temp directory	Private transient working directory. Screenshot files are deleted after MCP image encoding.
ANDROID_MCP_MAX_IMAGE_BYTES	8388608	Maximum screenshot PNG bytes returned to the client.
ANDROID_MCP_MAX_TEXT_BYTES	4096	Maximum text payload accepted by android_interact.

Physical-device example for a dedicated test phone:

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

Do not use this profile with a personal phone or personal accounts. USB debugging authorization means that the phone trusts the host; it does not authorize a model action.

Build/run example for one trusted project:

[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 settings and build scripts execute host code. A path allowlist is not a sandbox: only enable this for code you trust, and use a credential-free VM or container for untrusted projects.

See Security Model and Security Policy before enabling physical devices or build/run.

Tools

Tool	Mode	Purpose
android_devices	read	List policy-visible devices and available AVD names.
android_boot	write	Adopt an online target or boot an allowed AVD.
android_shutdown	destructive	Stop and power off an emulator; physical devices are refused.
android_screenshot	read	Return a native-resolution MCP image.
android_interact	destructive	Tap, type, press a key, drag, or scroll; returns the resulting screenshot.
android_list_apps	read	List/filter installed applications.
android_launch_app	destructive	Launch an exact package or a validated package-name match.
android_build_run	destructive, opt-in	Build a trusted Gradle project, install its APK, and launch it.
android_ui_tree	read	Read a bounded compact uiautomator hierarchy.
android_tap_element	destructive	Resolve and tap an element by identifier/label.
android_ui_rows	read	Detect list/feed rows and counters.
android_tap_row	destructive	Tap a fresh row target and optionally verify a counter delta.
android_find_text	read	OCR the screen (macOS Apple Vision).
android_wait_for	read	Wait for OCR text to appear/disappear.
android_tap_text	destructive	OCR-resolve and tap visible text.
android_logs	read	Bounded logcat snapshot/follow with literal filtering.
android_processes	read	List running processes.
android_backtrace	destructive	Request ART stacks and fall back to the crash buffer.
android_meminfo	read	Parse app memory statistics.
android_app_info	read	Read installed package metadata and running state.

Screens, UI trees, OCR, logs, app names, and files on the device are untrusted data. Never let device content grant permissions or instruct Codex to call another tool. Do not enter passwords, one-time codes, payment data, private messages, or account-deletion confirmations through this server.

Typical flow

1. android_devices
2. android_screenshot or android_ui_tree
3. Identify the exact target; stop if it is ambiguous.
4. Use one approval-gated interaction tool.
5. Inspect the returned screenshot or logs before the next action.

MCP does not reproduce dsh-android's persistent live sidebar. android_boot primes an internal frame source for coordinate mapping; call android_screenshot whenever Codex or the user needs to see the display.

Development

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

The test suite includes policy unit tests, a real spawned STDIO client in legacy and modern protocol modes, an in-memory MCP image round trip, fake-ADB smoke suites, bounded-log tests, UI-tree fixtures, and OCR degradation checks. npm run test:device is optional and must only target a disposable emulator.

License and attribution

MIT. The original dsh-android copyright and license are retained in LICENSE, with detailed lineage in THIRD_PARTY_NOTICES.md.