@us-all/android-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thkim-us
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,277 @@
+# Android MCP Server
+
+Android MCP server — ADB-based device management, UI automation, logcat debugging, emulator control, and more via the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+[한국어](./README_KO.md)
+
+## Why This Server?
+
+| Feature | Other Android MCPs | This Server |
+|---------|-------------------|-------------|
+| UI Automation (tap, swipe, screenshot) | ✓ | ✓ |
+| UI Hierarchy (accessibility tree) | ✓ | ✓ (compact mode for token efficiency) |
+| Logcat filtering & crash log extraction | — | ✓ |
+| Emulator lifecycle (AVD start/stop/snapshot) | — | ✓ |
+| File management (push/pull) | — | ✓ |
+| System info (battery, network, settings) | — | ✓ |
+| 2-tier security (write + shell gating) | — | ✓ |
+| Pure ADB (no Appium/uiautomator2 dependency) | — | ✓ |
+| TypeScript + official MCP SDK | — | ✓ |
+
+## Quick Start
+
+### 1. npx (recommended)
+
+```bash
+npx @us-all/android-mcp-server
+```
+
+### 2. Docker
+
+```bash
+docker run --rm \
+  --device /dev/bus/usb \
+  -e ANDROID_MCP_ALLOW_WRITE=true \
+  ghcr.io/us-all/android-mcp-server:latest
+```
+
+### 3. Build from source
+
+```bash
+git clone <repo>
+cd android-mcp-server
+pnpm install
+pnpm run build
+pnpm start
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `ANDROID_HOME` | No | auto-detect | Android SDK path |
+| `ADB_PATH` | No | `adb` (PATH) | Path to ADB binary |
+| `ANDROID_SERIAL` | No | auto (single device) | Target device serial number |
+| `ANDROID_MCP_ALLOW_WRITE` | No | `false` | Enable write operations (install, tap, push, etc.) |
+| `ANDROID_MCP_ALLOW_SHELL` | No | `false` | Enable arbitrary shell command execution |
+
+### Read-Only Mode (default)
+
+By default, only read operations are permitted. Write operations (`tap`, `install-app`, `push-file`, etc.) return an error unless `ANDROID_MCP_ALLOW_WRITE=true` is set. Shell command execution requires a separate `ANDROID_MCP_ALLOW_SHELL=true` flag for additional security.
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "android": {
+      "command": "npx",
+      "args": ["@us-all/android-mcp-server"],
+      "env": {
+        "ANDROID_MCP_ALLOW_WRITE": "true"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "android": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@us-all/android-mcp-server"],
+      "env": {
+        "ANDROID_MCP_ALLOW_WRITE": "true",
+        "ANDROID_MCP_ALLOW_SHELL": "true"
+      }
+    }
+  }
+}
+```
+
+Or from a local build:
+
+```json
+{
+  "mcpServers": {
+    "android": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["dist/index.js"],
+      "cwd": "/path/to/android-mcp-server",
+      "env": {
+        "ANDROID_MCP_ALLOW_WRITE": "true",
+        "ANDROID_MCP_ALLOW_SHELL": "true"
+      }
+    }
+  }
+}
+```
+
+## Tools (35)
+
+### Device (5)
+
+| Tool | Description | R/W |
+|------|-------------|-----|
+| `list-devices` | List connected devices and emulators with status | R |
+| `get-device-info` | Device model, brand, Android version, SDK, display info | R |
+| `get-device-properties` | System properties via getprop (filterable by prefix) | R |
+| `connect-device` | Connect to device over TCP/IP (wireless ADB) | W |
+| `disconnect-device` | Disconnect TCP/IP device | W |
+
+### Apps (6)
+
+| Tool | Description | R/W |
+|------|-------------|-----|
+| `list-packages` | List installed packages (filter by name, type: all/system/3rd-party) | R |
+| `get-package-info` | Package version, SDK targets, install time, permissions | R |
+| `install-app` | Install APK file on device | W |
+| `uninstall-app` | Uninstall app (optionally keep data) | W |
+| `launch-app` | Launch app by package name (or specific activity) | W |
+| `stop-app` | Force stop an app | W |
+
+### UI Automation (7)
+
+| Tool | Description | R/W |
+|------|-------------|-----|
+| `take-screenshot` | Capture screen as PNG image (returned as base64) | R |
+| `dump-ui-hierarchy` | Dump accessibility tree — compact mode returns interactive elements only with center coordinates for token efficiency | R |
+| `tap` | Tap at (x, y) coordinates | W |
+| `long-press` | Long press at (x, y) with configurable duration | W |
+| `swipe` | Swipe gesture from (x1,y1) to (x2,y2) | W |
+| `input-text` | Type text (special characters escaped) | W |
+| `press-key` | Key event: BACK, HOME, ENTER, VOLUME_UP, etc. | W |
+
+### Logcat (4)
+
+| Tool | Description | R/W |
+|------|-------------|-----|
+| `get-logcat` | Get recent logs with tag and priority filter (V/D/I/W/E/F) | R |
+| `clear-logcat` | Clear logcat buffer | W |
+| `search-logcat` | Search logs by text pattern (case-insensitive supported) | R |
+| `get-crash-logs` | Extract crash/fatal logs, optionally filtered by package | R |
+
+### Emulator (5)
+
+| Tool | Description | R/W |
+|------|-------------|-----|
+| `list-avds` | List available Android Virtual Devices | R |
+| `start-emulator` | Start AVD (supports headless mode, data wipe) | W |
+| `stop-emulator` | Stop a running emulator | W |
+| `list-snapshots` | List emulator snapshots | R |
+| `load-snapshot` | Load an emulator snapshot | W |
+
+### Files (4)
+
+| Tool | Description | R/W |
+|------|-------------|-----|
+| `list-files` | List files on device (supports recursive) | R |
+| `pull-file` | Download file from device to local filesystem | R |
+| `push-file` | Upload local file to device | W |
+| `delete-file` | Delete file or directory on device | W |
+
+### System (3)
+
+| Tool | Description | R/W |
+|------|-------------|-----|
+| `get-battery-info` | Battery level, charging state, temperature, health | R |
+| `get-network-info` | WiFi status, IP address, connectivity details | R |
+| `change-setting` | Modify system/secure/global settings | W |
+
+### Shell (1)
+
+| Tool | Description | R/W |
+|------|-------------|-----|
+| `execute-shell` | Execute arbitrary ADB shell command (requires `ANDROID_MCP_ALLOW_SHELL`) | W |
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│                 Claude / AI Client                   │
+└─────────────────────┬────────────────────────────────┘
+                      │ MCP Protocol (stdio)
+                      ▼
+┌──────────────────────────────────────────────────────┐
+│           android-mcp-server (index.ts)              │
+│                                                      │
+│  ┌─────────┐  ┌──────────────────────────────────┐   │
+│  │config.ts│  │          tools/                   │   │
+│  │ ADB path│  │  device.ts  ── 5 tools           │   │
+│  │ serial  │  │  apps.ts    ── 6 tools           │   │
+│  │ perms   │  │  ui.ts      ── 7 tools           │   │
+│  └─────────┘  │  logcat.ts  ── 4 tools           │   │
+│               │  emulator.ts── 5 tools           │   │
+│  ┌─────────┐  │  files.ts   ── 4 tools           │   │
+│  │ adb.ts  │  │  system.ts  ── 3 tools           │   │
+│  │ wrapper │  │  shell.ts   ── 1 tool            │   │
+│  └─────────┘  │  utils.ts   ── error handling    │   │
+│               └──────────────────────────────────┘   │
+└─────────────────────┬────────────────────────────────┘
+                      │ child_process (execFile)
+                      ▼
+┌──────────────────────────────────────────────────────┐
+│              ADB (Android Debug Bridge)              │
+│                                                      │
+│         USB / TCP-IP / Emulator connection            │
+└─────────────────────┬────────────────────────────────┘
+                      │
+                      ▼
+               Android Device
+```
+
+## Tech Stack
+
+- **Runtime:** Node.js 18+
+- **Language:** TypeScript 5.x (strict mode, ESM)
+- **MCP SDK:** @modelcontextprotocol/sdk 1.27+
+- **Validation:** zod 4.x
+- **XML Parser:** fast-xml-parser (UI hierarchy parsing)
+- **Android:** ADB via child_process (no Appium, no uiautomator2)
+- **Testing:** vitest (fork pool isolation)
+- **Package Manager:** pnpm
+
+## Security
+
+- **Read-only by default** — All write operations blocked unless `ANDROID_MCP_ALLOW_WRITE=true`
+- **Shell gating** — Arbitrary shell commands require separate `ANDROID_MCP_ALLOW_SHELL=true`
+- **Error sanitization** — API keys, tokens, passwords redacted from all error outputs
+- **Input validation** — All parameters validated via zod schemas before execution
+- **No ambient authority** — No global state mutation; explicit device targeting via serial
+
+## Development
+
+```bash
+pnpm install          # Install dependencies
+pnpm run dev          # Watch mode (tsc --watch)
+pnpm run build        # Compile TypeScript → dist/
+pnpm test             # Run unit tests
+pnpm start            # Run MCP server
+```
+
+### Adding a new tool
+
+1. Define zod schema + async handler in `src/tools/<category>.ts`
+2. Import and register with `server.tool()` in `src/index.ts`
+3. Use `wrapToolHandler()` for consistent response formatting
+4. Use `assertWriteAllowed()` for write operations
+5. Run `pnpm run build && pnpm test`
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development guidelines.
+
+## License
+
+MIT

package/dist/adb.d.ts

@@ -0,0 +1,8 @@
+export interface AdbOptions {
+    serial?: string;
+    timeout?: number;
+}
+export declare function adb(args: string[], options?: AdbOptions): Promise<string>;
+export declare function adbShell(command: string, options?: AdbOptions): Promise<string>;
+export declare function adbRawBuffer(args: string[], options?: AdbOptions): Promise<Buffer>;
+//# sourceMappingURL=adb.d.ts.map

package/dist/adb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adb.d.ts","sourceRoot":"","sources":["../src/adb.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAUD,wBAAsB,GAAG,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,MAAM,CAAC,CAWjB"}

package/dist/adb.js

@@ -0,0 +1,35 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { config } from "./config.js";
+const execFileAsync = promisify(execFile);
+const DEFAULT_TIMEOUT = 30_000;
+function buildArgs(args, options) {
+    const serial = options?.serial ?? config.serial;
+    if (serial) {
+        return ["-s", serial, ...args];
+    }
+    return args;
+}
+export async function adb(args, options) {
+    const fullArgs = buildArgs(args, options);
+    const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+    const { stdout } = await execFileAsync(config.adbPath, fullArgs, {
+        timeout,
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    return stdout.trim();
+}
+export async function adbShell(command, options) {
+    return adb(["shell", command], options);
+}
+export async function adbRawBuffer(args, options) {
+    const fullArgs = buildArgs(args, options);
+    const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+    const { stdout } = await execFileAsync(config.adbPath, fullArgs, {
+        timeout,
+        maxBuffer: 10 * 1024 * 1024,
+        encoding: "buffer",
+    });
+    return stdout;
+}
+//# sourceMappingURL=adb.js.map

package/dist/adb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adb.js","sourceRoot":"","sources":["../src/adb.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,MAAM,eAAe,GAAG,MAAM,CAAC;AAO/B,SAAS,SAAS,CAAC,IAAc,EAAE,OAAoB;IACrD,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC;IAChD,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,GAAG,CACvB,IAAc,EACd,OAAoB;IAEpB,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,eAAe,CAAC;IAEpD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE;QAC/D,OAAO;QACP,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;KAC5B,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;AACvB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,OAAe,EACf,OAAoB;IAEpB,OAAO,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAc,EACd,OAAoB;IAEpB,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,eAAe,CAAC;IAEpD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE;QAC/D,OAAO;QACP,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;QAC3B,QAAQ,EAAE,QAAQ;KACnB,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export declare const config: {
+    androidHome: string;
+    adbPath: string;
+    serial: string;
+    allowWrite: boolean;
+    allowShell: boolean;
+};
+export declare function validateConfig(): Promise<void>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,MAAM;;;;;;CAMlB,CAAC;AAEF,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CASpD"}

package/dist/config.js

@@ -0,0 +1,22 @@
+import dotenv from "dotenv";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+dotenv.config();
+const execFileAsync = promisify(execFile);
+export const config = {
+    androidHome: process.env.ANDROID_HOME ?? "",
+    adbPath: process.env.ADB_PATH ?? "adb",
+    serial: process.env.ANDROID_SERIAL ?? "",
+    allowWrite: process.env.ANDROID_MCP_ALLOW_WRITE === "true",
+    allowShell: process.env.ANDROID_MCP_ALLOW_SHELL === "true",
+};
+export async function validateConfig() {
+    try {
+        await execFileAsync(config.adbPath, ["version"]);
+    }
+    catch {
+        throw new Error(`ADB not found at "${config.adbPath}". ` +
+            "Install Android SDK and ensure adb is in PATH, or set ADB_PATH environment variable.");
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,CAAC,MAAM,EAAE,CAAC;AAEhB,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,EAAE;IAC3C,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,KAAK;IACtC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE;IACxC,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,MAAM;IAC1D,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,MAAM;CAC3D,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,IAAI,CAAC;QACH,MAAM,aAAa,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,qBAAqB,MAAM,CAAC,OAAO,KAAK;YACtC,sFAAsF,CACzF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { validateConfig } from "./config.js";
+import { wrapToolHandler, wrapImageToolHandler } from "./tools/utils.js";
+// Device tools
+import { listDevicesSchema, listDevices, getDeviceInfoSchema, getDeviceInfo, getDevicePropertiesSchema, getDeviceProperties, connectDeviceSchema, connectDevice, disconnectDeviceSchema, disconnectDevice, } from "./tools/device.js";
+// App tools
+import { listPackagesSchema, listPackages, getPackageInfoSchema, getPackageInfo, installAppSchema, installApp, uninstallAppSchema, uninstallApp, launchAppSchema, launchApp, stopAppSchema, stopApp, } from "./tools/apps.js";
+// UI tools
+import { takeScreenshotSchema, takeScreenshot, dumpUiHierarchySchema, dumpUiHierarchy, tapSchema, tap, longPressSchema, longPress, swipeSchema, swipe, inputTextSchema, inputText, pressKeySchema, pressKey, } from "./tools/ui.js";
+// Logcat tools
+import { getLogcatSchema, getLogcat, clearLogcatSchema, clearLogcat, searchLogcatSchema, searchLogcat, getCrashLogsSchema, getCrashLogs, } from "./tools/logcat.js";
+// Emulator tools
+import { listAvdsSchema, listAvds, startEmulatorSchema, startEmulator, stopEmulatorSchema, stopEmulator, listSnapshotsSchema, listSnapshots, loadSnapshotSchema, loadSnapshot, } from "./tools/emulator.js";
+// File tools
+import { listFilesSchema, listFiles, pullFileSchema, pullFile, pushFileSchema, pushFile, deleteFileSchema, deleteFile, } from "./tools/files.js";
+// Shell tools
+import { executeShellSchema, executeShell } from "./tools/shell.js";
+// System tools
+import { getBatteryInfoSchema, getBatteryInfo, getNetworkInfoSchema, getNetworkInfo, changeSettingSchema, changeSetting, } from "./tools/system.js";
+// --- Server setup ---
+await validateConfig();
+const server = new McpServer({
+    name: "android-mcp-server",
+    version: "1.0.0",
+});
+// ========== Device tools ==========
+server.tool("list-devices", "List all connected Android devices and emulators with their status and details", listDevicesSchema.shape, wrapToolHandler(listDevices));
+server.tool("get-device-info", "Get detailed device information including model, brand, Android version, SDK version, display density and size", getDeviceInfoSchema.shape, wrapToolHandler(getDeviceInfo));
+server.tool("get-device-properties", "Get Android system properties (getprop). Optionally filter by prefix like 'ro.build' or 'ro.product'", getDevicePropertiesSchema.shape, wrapToolHandler(getDeviceProperties));
+server.tool("connect-device", "Connect to a device over TCP/IP (wireless ADB). Requires ANDROID_MCP_ALLOW_WRITE=true", connectDeviceSchema.shape, wrapToolHandler(connectDevice));
+server.tool("disconnect-device", "Disconnect a TCP/IP device or all TCP/IP devices. Requires ANDROID_MCP_ALLOW_WRITE=true", disconnectDeviceSchema.shape, wrapToolHandler(disconnectDevice));
+// ========== App tools ==========
+server.tool("list-packages", "List installed packages on the device. Filter by name or type (all, system, third-party)", listPackagesSchema.shape, wrapToolHandler(listPackages));
+server.tool("get-package-info", "Get detailed package info: version, SDK targets, install time, permissions", getPackageInfoSchema.shape, wrapToolHandler(getPackageInfo));
+server.tool("install-app", "Install an APK file on the device. Requires ANDROID_MCP_ALLOW_WRITE=true", installAppSchema.shape, wrapToolHandler(installApp));
+server.tool("uninstall-app", "Uninstall an app from the device. Requires ANDROID_MCP_ALLOW_WRITE=true", uninstallAppSchema.shape, wrapToolHandler(uninstallApp));
+server.tool("launch-app", "Launch an app by package name. Optionally specify activity. Requires ANDROID_MCP_ALLOW_WRITE=true", launchAppSchema.shape, wrapToolHandler(launchApp));
+server.tool("stop-app", "Force stop an app by package name. Requires ANDROID_MCP_ALLOW_WRITE=true", stopAppSchema.shape, wrapToolHandler(stopApp));
+// ========== UI tools ==========
+server.tool("take-screenshot", "Capture a screenshot of the device screen. Returns a PNG image", takeScreenshotSchema.shape, wrapImageToolHandler(takeScreenshot));
+server.tool("dump-ui-hierarchy", "Dump the UI accessibility tree. Compact mode (default) returns only interactive elements with coordinates for token efficiency", dumpUiHierarchySchema.shape, wrapToolHandler(dumpUiHierarchy));
+server.tool("tap", "Tap at specific screen coordinates. Requires ANDROID_MCP_ALLOW_WRITE=true", tapSchema.shape, wrapToolHandler(tap));
+server.tool("long-press", "Long press at specific screen coordinates. Requires ANDROID_MCP_ALLOW_WRITE=true", longPressSchema.shape, wrapToolHandler(longPress));
+server.tool("swipe", "Swipe from one point to another. Requires ANDROID_MCP_ALLOW_WRITE=true", swipeSchema.shape, wrapToolHandler(swipe));
+server.tool("input-text", "Type text on the device. Focus an input field first using tap. Requires ANDROID_MCP_ALLOW_WRITE=true", inputTextSchema.shape, wrapToolHandler(inputText));
+server.tool("press-key", "Press a key event (BACK, HOME, ENTER, VOLUME_UP, etc). Requires ANDROID_MCP_ALLOW_WRITE=true", pressKeySchema.shape, wrapToolHandler(pressKey));
+// ========== Logcat tools ==========
+server.tool("get-logcat", "Get recent logcat output. Filter by tag, priority level, and number of lines", getLogcatSchema.shape, wrapToolHandler(getLogcat));
+server.tool("clear-logcat", "Clear the logcat buffer. Requires ANDROID_MCP_ALLOW_WRITE=true", clearLogcatSchema.shape, wrapToolHandler(clearLogcat));
+server.tool("search-logcat", "Search logcat for a text pattern. Supports case-sensitive and case-insensitive search", searchLogcatSchema.shape, wrapToolHandler(searchLogcat));
+server.tool("get-crash-logs", "Get crash logs from the device. Optionally filter by package name", getCrashLogsSchema.shape, wrapToolHandler(getCrashLogs));
+// ========== Emulator tools ==========
+server.tool("list-avds", "List available Android Virtual Devices (AVDs) that can be started", listAvdsSchema.shape, wrapToolHandler(listAvds));
+server.tool("start-emulator", "Start an Android emulator by AVD name. Supports headless mode and data wipe. Requires ANDROID_MCP_ALLOW_WRITE=true", startEmulatorSchema.shape, wrapToolHandler(startEmulator));
+server.tool("stop-emulator", "Stop a running Android emulator. Requires ANDROID_MCP_ALLOW_WRITE=true", stopEmulatorSchema.shape, wrapToolHandler(stopEmulator));
+server.tool("list-snapshots", "List available emulator snapshots", listSnapshotsSchema.shape, wrapToolHandler(listSnapshots));
+server.tool("load-snapshot", "Load an emulator snapshot. Requires ANDROID_MCP_ALLOW_WRITE=true", loadSnapshotSchema.shape, wrapToolHandler(loadSnapshot));
+// ========== File tools ==========
+server.tool("list-files", "List files on the device at a given path. Supports recursive listing", listFilesSchema.shape, wrapToolHandler(listFiles));
+server.tool("pull-file", "Pull (download) a file from the device to local filesystem", pullFileSchema.shape, wrapToolHandler(pullFile));
+server.tool("push-file", "Push (upload) a local file to the device. Requires ANDROID_MCP_ALLOW_WRITE=true", pushFileSchema.shape, wrapToolHandler(pushFile));
+server.tool("delete-file", "Delete a file or directory on the device. Requires ANDROID_MCP_ALLOW_WRITE=true", deleteFileSchema.shape, wrapToolHandler(deleteFile));
+// ========== Shell tools ==========
+server.tool("execute-shell", "Execute an arbitrary ADB shell command. Requires ANDROID_MCP_ALLOW_SHELL=true (separate from write permission for security)", executeShellSchema.shape, wrapToolHandler(executeShell));
+// ========== System tools ==========
+server.tool("get-battery-info", "Get battery status including level, charging state, temperature, and health", getBatteryInfoSchema.shape, wrapToolHandler(getBatteryInfo));
+server.tool("get-network-info", "Get network information including WiFi status, IP address, and connectivity details", getNetworkInfoSchema.shape, wrapToolHandler(getNetworkInfo));
+server.tool("change-setting", "Change an Android system setting (system/secure/global namespace). Requires ANDROID_MCP_ALLOW_WRITE=true", changeSettingSchema.shape, wrapToolHandler(changeSetting));
+// --- Start server ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Android MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/apps.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+export declare const listPackagesSchema: z.ZodObject<{
+    filter: z.ZodOptional<z.ZodString>;
+    type: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        system: "system";
+        "third-party": "third-party";
+    }>>>;
+    serial: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const getPackageInfoSchema: z.ZodObject<{
+    packageName: z.ZodString;
+    serial: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const installAppSchema: z.ZodObject<{
+    apkPath: z.ZodString;
+    replace: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    serial: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const uninstallAppSchema: z.ZodObject<{
+    packageName: z.ZodString;
+    keepData: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    serial: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const launchAppSchema: z.ZodObject<{
+    packageName: z.ZodString;
+    activity: z.ZodOptional<z.ZodString>;
+    serial: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const stopAppSchema: z.ZodObject<{
+    packageName: z.ZodString;
+    serial: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function listPackages(params: z.infer<typeof listPackagesSchema>): Promise<{
+    count: number;
+    packages: string[];
+}>;
+export declare function getPackageInfo(params: z.infer<typeof getPackageInfoSchema>): Promise<Record<string, string | string[]>>;
+export declare function installApp(params: z.infer<typeof installAppSchema>): Promise<{
+    result: string;
+}>;
+export declare function uninstallApp(params: z.infer<typeof uninstallAppSchema>): Promise<{
+    result: string;
+}>;
+export declare function launchApp(params: z.infer<typeof launchAppSchema>): Promise<{
+    result: string;
+}>;
+export declare function stopApp(params: z.infer<typeof stopAppSchema>): Promise<{
+    result: string;
+}>;
+//# sourceMappingURL=apps.d.ts.map

package/dist/tools/apps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/tools/apps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,kBAAkB;;;;;;;;iBAc7B,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;iBAQ/B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;iBAW3B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;iBAa7B,CAAC;AAEH,eAAO,MAAM,eAAe;;;;iBAc1B,CAAC;AAEH,eAAO,MAAM,aAAa;;;iBAQxB,CAAC;AAIH,wBAAsB,YAAY,CAChC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC;;;GAwB3C;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,8CA8C7C;AAED,wBAAsB,UAAU,CAC9B,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC;;GASzC;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC;;GAS3C;AAED,wBAAsB,SAAS,CAC7B,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC;;GAgBxC;AAED,wBAAsB,OAAO,CAC3B,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC;;GAMtC"}