Android MCP 🤖✨

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)

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:

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

npm test

📱 Optional: Build/install the demo app

Only needed if you want to exercise the sample Android UI:

# 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.