Android MCP Server

A production-grade MCP (Model Context Protocol) server that gives any AI agent full control over Android devices via ADB, UIAutomator, Accessibility, and Vision (screenshots).

Features

• 30+ MCP Tools — Device control, app management, UI automation, vision, testing
• Multi-Device Support — Control multiple Android devices simultaneously
• Smart Execution — UIAutomator → Accessibility → Vision → Coordinates fallback
• Security — Input sanitization, rate limiting, device allowlisting, destructive op protection
• Automation — Action recording/replay, test scenarios, state tracking
• Observability — Structured JSON logs, per-tool metrics, action history

Prerequisites

• Node.js ≥ 18
• ADB installed and on PATH (Android SDK Platform Tools)
• An Android device or emulator connected via USB/WiFi

Verify ADB is working:

adb devices

Setup

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run the server
npm start

MCP Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "android": {
      "command": "node",
      "args": ["repo_path/dist/mcp/server.js"],
      "env": {
        "ADB_PATH": "adb"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "android": {
      "command": "node",
      "args": ["repo_path/dist/mcp/server.js"]
    }
  }
}

Generic MCP Client (stdio)

node dist/mcp/server.js

The server communicates via stdin/stdout using the MCP JSON-RPC protocol.

Configuration

Create android-mcp.config.json in the project root (optional):

{
  "adbPath": "adb",
  "allowedDevices": [],
  "maxActionsPerMinute": 120,
  "commandTimeoutMs": 30000,
  "maxRetries": 3,
  "debug": false,
  "screenshotDir": "./screenshots",
  "recordingsDir": "./recordings",
  "allowDestructiveOps": false
}

Or use environment variables:

Available Tools

Device Management

Input Controls

App Management

File System

UI Automation (UIAutomator)

Vision

Automation & Testing

Architecture

src/
├── mcp/
│   └── server.ts           # MCP server entry point
├── controllers/
│   ├── device-tools.ts      # Device MCP tools
│   ├── input-tools.ts       # Input MCP tools
│   ├── app-tools.ts         # App management MCP tools
│   ├── file-tools.ts        # File system MCP tools
│   ├── ui-tools.ts          # UIAutomator MCP tools
│   ├── vision-tools.ts      # Vision MCP tools
│   └── automation-tools.ts  # Automation MCP tools
├── adb/
│   ├── adb-executor.ts      # Safe ADB command execution
│   ├── device-manager.ts    # Device discovery & sessions
│   ├── input-controller.ts  # Touch/key input
│   ├── app-manager.ts       # App lifecycle
│   └── file-manager.ts      # File operations
├── uiautomator/
│   ├── ui-tree-parser.ts    # XML → JSON conversion
│   ├── element-finder.ts    # Element search & interaction
│   └── element-cache.ts     # LRU element cache
├── vision/
│   ├── screenshot.ts        # Screenshot capture
│   ├── screen-diff.ts       # Screenshot comparison
│   └── visual-analyzer.ts   # AI-ready screen analysis
├── accessibility/
│   ├── accessibility-bridge.ts  # Accessibility fallback
│   └── smart-executor.ts       # Multi-strategy executor
├── automation/
│   ├── action-recorder.ts   # Action recording
│   ├── action-replayer.ts   # Action replay
│   ├── test-runner.ts       # Test scenarios
│   └── state-tracker.ts     # Device state memory
├── security/
│   ├── validator.ts         # Input sanitization
│   └── rate-limiter.ts      # Rate limiting
└── utils/
    ├── logger.ts            # Structured logging
    ├── config.ts            # Configuration
    ├── errors.ts            # Error hierarchy
    ├── retry.ts             # Retry logic
    └── metrics.ts           # Performance tracking

Testing

npm test
npm run test:coverage

Development

# Run in development mode (ts-node)
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/mcp/server.js

License

MIT