{
  "markdown": "# expo-android\n\n[![npm version](https://img.shields.io/npm/v/@fndchagas/expo-android.svg)](https://www.npmjs.com/package/@fndchagas/expo-android)\n[![npm downloads](https://img.shields.io/npm/dm/@fndchagas/expo-android.svg)](https://www.npmjs.com/package/@fndchagas/expo-android)\n[![license](https://img.shields.io/npm/l/@fndchagas/expo-android.svg)](LICENSE)\n[![node version](https://img.shields.io/node/v/@fndchagas/expo-android.svg)](package.json)\n[![typescript](https://img.shields.io/badge/TypeScript-5.9.3-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![CI](https://github.com/frndchagas/expo-android/actions/workflows/ci.yml/badge.svg)](https://github.com/frndchagas/expo-android/actions/workflows/ci.yml)\n\nMCP server for Android emulator automation via ADB.\n\n## Requirements\n\n- Node 18+\n- Android SDK platform-tools (adb) available\n- Android emulator or device connected\n\nVerify adb:\n\n```bash\nadb devices\n```\n\n## Install\n\n**Claude Desktop, one-click:** download [`expo-android.mcpb`](https://github.com/frndchagas/expo-android/releases/latest/download/expo-android.mcpb) from the latest release and drag it into **Settings → Extensions**. You can leave both fields empty — adb is auto-detected and the only connected device is used by default.\n\n**Via npm:**\n\n```bash\nnpm install -g @fndchagas/expo-android\n# or\nnpx -y @fndchagas/expo-android\n```\n\n## Quickstart\n\n1. Start an emulator or connect a device.\n2. Run `doctor` to validate adb + device selection.\n3. Use `inspect`, `tapElement`, `inputText`, etc.\n\nExample:\n\n```ts\nawait client.callTool({ name: 'expo-android.doctor', arguments: {} });\nawait client.callTool({\n  name: 'expo-android.inspect',\n  arguments: { onlyInteractive: true, maxElements: 200 },\n});\n```\n\n## Use with Claude Code CLI\n\n```bash\nclaude mcp add expo-android \\\n  --env ADB_PATH=\"$HOME/Library/Android/sdk/platform-tools/adb\" \\\n  --env ADB_SERIAL=\"auto\" \\\n  -- npx -y @fndchagas/expo-android\n```\n\n## Use with OpenAI Codex CLI\n\n```bash\ncodex mcp add expo-android \\\n  --env ADB_PATH=\"$HOME/Library/Android/sdk/platform-tools/adb\" \\\n  --env ADB_SERIAL=\"auto\" \\\n  -- npx -y @fndchagas/expo-android\n```\n\nOr edit `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.expo-android]\ncommand = \"npx\"\nargs = [\"-y\", \"@fndchagas/expo-android\"]\nenv = { ADB_PATH = \"/Users/you/Library/Android/sdk/platform-tools/adb\", ADB_SERIAL = \"emulator-5554\" }\n```\n\nSerial selection priority:\n`serial` param (per tool call) → `setDevice` override → `ADB_SERIAL` env → auto (if only one device).\n\n## Environment variables\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `ADB_PATH` | `adb` | Path to adb executable |\n| `ADB_SERIAL` | optional | Device serial to target (`auto` to clear and auto-detect) |\n| `ADB_TIMEOUT_MS` | `15000` | Timeout for adb commands |\n| `ADB_MAX_BUFFER_MB` | `10` | Max output buffer size |\n| `ADB_DEBUG` | `0` | Log adb diagnostics to stderr |\n| `MCP_TRANSPORT` | `stdio` | Transport: `stdio`, `http`, or `both` |\n| `PORT` | `7332` | HTTP port when using http/both |\n\n## Troubleshooting\n\n### adb not found (spawn adb ENOENT)\n\nThe server starts even when adb is missing — tools return the `ADB executable not found`\nerror until adb becomes reachable (run `doctor` to diagnose). To fix it, set `ADB_PATH`\nor export an SDK path:\n\n```bash\nexport ADB_PATH=\"$HOME/Library/Android/sdk/platform-tools/adb\"\n# or\nexport ANDROID_HOME=\"$HOME/Library/Android/sdk\"\n```\n\nIf multiple devices are connected, set `ADB_SERIAL` to the target device.\nYou can also run `setDevice` at runtime:\n\n```ts\nawait client.callTool({\n  name: 'expo-android.setDevice',\n  arguments: { serial: 'emulator-5554' },\n});\n```\n\nIf you update PATH or SDK variables, restart the MCP process so it can pick up\nthe new environment.\n\n## Tests\n\n```bash\nnpm run build\nnpm test\n```\n\n## Tools\n\nTool names are plain identifiers (e.g. `tap`); your MCP client prefixes them with the server name you registered.\n\n- `devices` — list connected devices and emulators.\n- `doctor` — validate adb availability and show connected devices.\n- `setDevice` — override the active device serial for this MCP process.\n- `inspect` — UI dump parsed into elements with a summary (screenshot optional).\n- `screenshot` — capture a screenshot only (base64 or file path).\n- `findElement` — return elements that match search criteria.\n- `tapElement` — find an element and tap its center.\n- `waitForElement` — wait until an element appears (optionally with state checks).\n- `assertElement` — verify element existence and state.\n- `tap` — tap at x/y coordinates.\n- `swipe` — swipe between coordinates.\n- `longPress` — press and hold at coordinates.\n- `inputText` — type text in the focused field.\n- `keyEvent` — send Android key events (e.g., BACK, HOME).\n- `openApp` — launch an app by package name.\n- `listPackages` — list installed package names.\n- `installExpoGo` — download the pinned Expo Go APK and install it via `adb install -r` (the `url` override only accepts official `github.com/expo/expo-go-releases` URLs).\n\nEvery tool declares MCP annotations (`readOnlyHint`/`destructiveHint`), so clients can auto-approve inspection tools and gate the ones that drive the device.\n\n## Search criteria\n\nThese tools accept flexible search inputs: `findElement`, `tapElement`,\n`waitForElement`, `assertElement`.\n\nCommon fields:\n- `text`, `textContains`\n- `contentDesc`, `contentDescContains`\n- `resourceId`, `resourceIdContains`\n- `class`\n- `normalizeWhitespace`, `caseInsensitive`\n\n## MCP usage examples\n\n### Inspect\n\n```ts\nconst result = await client.callTool({\n  name: 'expo-android.inspect',\n  arguments: { onlyInteractive: true, includeScreenshot: false, maxElements: 200 },\n});\n```\n\nInspect options:\n- `includeScreenshot` (default: `false`)\n- `screenshotMode`: `base64` or `path`\n- `screenshotPath`: optional file path when using `path`\n- `maxElements`: limit elements returned\n- `includeElements`: return elements or summary only\n\n### Doctor\n\n```ts\nawait client.callTool({\n  name: 'expo-android.doctor',\n  arguments: {},\n});\n```\n\n### Override serial per call\n\n```ts\nawait client.callTool({\n  name: 'expo-android.tapElement',\n  arguments: { text: 'Search', serial: 'emulator-5554' },\n});\n```\n\n### Tap element\n\n```ts\nawait client.callTool({\n  name: 'expo-android.tapElement',\n  arguments: { text: 'Private account' },\n});\n```\n\n### Wait + assert\n\n```ts\nawait client.callTool({\n  name: 'expo-android.waitForElement',\n  arguments: { text: 'Save', timeout: 10000, shouldBeClickable: true },\n});\n\nawait client.callTool({\n  name: 'expo-android.assertElement',\n  arguments: { text: 'Private account', shouldBeChecked: true },\n});\n```\n",
  "bytes": 6614,
  "sha": "324e979a68d2ec2793243d9a0b96d881a94323046cffcb0b7051a0a6a16600a3",
  "repo_slug": "frndchagas/expo-android",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_frndchagas_expo_android_00134c7a/readme"
}