Android MCP

# Android MCP 🤖✨ [](#) [](#-requirements) [](#-requirements) [](#-notes--limits) Friendly MCP stdio server that chats with Android devices over ADB using `@devicefarmer/adbkit`, speaking newline-delimited JSON-RPC via `@modelcontextprotocol/sdk` (no `Content-Length` headers needed). Plug it into Cursor/Claude MCP and start poking at devices. ## ✨ What is this? - MCP transport that forwards handy ADB actions (tap, text, screenshot, UI dump, etc). - Uses newline-delimited JSON on stdin/stdout; one request per line, one response per line. - Prototype-friendly: swap out the minimal JSON-RPC loop for a full MCP SDK later if you want. ## 📦 Requirements - Node.js 18+ and npm. - ADB on PATH (e.g., Android SDK platform-tools). Keep `adb start-server` running. - At least one device or emulator attached (`adb devices`). - Optional: Android SDK/Gradle only if you plan to build the demo app; not needed for the MCP server itself. ## 🚀 Setup (local) ```bash git clone <repo-url> android-mcp cd android-mcp npm ci # or npm install npm test # stdio + tsconfig smoke tests npm run dev # start MCP server with tsx # or explicitly: npx --yes tsx src/server.ts ``` To build output: `npm run build` (emits `dist/`). Keep `adb devices` happy before invoking tools. ## 🧰 MCP config (Cursor/Claude) Example `~/.cursor/mcp.json` entry: ```json { "mcpServers": { "android-mcp": { "type": "stdio", "command": "npx", "args": ["--yes", "tsx", "/home/ivan/code/android-mcp/src/server.ts"], "cwd": "/home/ivan/code/android-mcp" } } } ``` ## 🎮 Tools exposed - `selectDevice` `{ serial }` → set default device for subsequent calls. - `keyEvent` `{ keyCode, serial? }` → send `input keyevent`. - `tap` `{ x, y, serial? }` - `text` `{ text, serial? }` → uses `input text` (spaces become `%s`). - `startActivity` `{ component, serial? }` → e.g. `"org.example/.MainActivity"`. - `screenshot` `{ serial? }` → `{ mimeType: "image/png", base64 }`. - `uiDump` `{ serial? }` → parsed `uiautomator dump` tree (text, contentDesc, resourceId, bounds). - `findAndTap` `{ text?, contentDesc?, serial? }` → finds the first matching node and taps its center. - `listDevicesDetailed` → lists attached devices with model/manufacturer/sdk info. ## 📸 Notes & limits - Screenshot and UI dump are periodic snapshots (no streaming yet). - UI dump depends on `uiautomator` being present on the device. - Prototype transport; you can wire in a richer MCP SDK without changing the ADB helpers. ## 🧪 Tests ```bash npm test ``` ## 📱 Optional: Build/install the demo app Only needed if you want to exercise the sample Android UI: ```bash # from the parent monorepo that contains the Android app ./gradlew assembleDebug adb install -r app/build/outputs/apk/debug/app-debug.apk adb shell am start -n org.dronix.android.kindlegratis/.MainActivity ``` ## 🛠️ CI hints - Node workflow: checkout → setup-node 18+ → `npm ci` → `npm test`. - If building the Android app in CI, add Java 17 + Android SDK setup and run `./gradlew assembleDebug`.