Android Screenshot MCP Server

MCP server for taking screenshots of Android devices over WiFi. Useful for UI debugging and visual inspection during development.

Features

• Wireless screenshot capture via ADB
• Automatic device detection and connection
• Smart pairing for first-time setup
• UI/UX debugging and layout inspection

Setup

1. Install dependencies:

   npm install
   

2. Add to Claude Code:

   claude mcp add android /path/to/android-screenshot-mcp/src/index.js
   

3. Enable wireless debugging on your Android device:

   • Settings → Developer Options → Wireless Debugging
   • Note the IP address and ports shown

Usage

The tool automatically detects connected devices. If no device is connected, it will guide you through the setup.

Quick Usage

For already connected devices:

screenshot phone

For new connections, provide the IP and port shown in your device's wireless debugging settings:

screenshot phone with 192.168.1.100:41737

First-time Setup

If this is your first time connecting, you'll need to pair first:

screenshot phone with 192.168.1.100:41737 and pairing code 123456 port 54321

The tool accepts several formats:

• deviceIP: "192.168.1.100:41737" - IP with port included
• deviceIP: "192.168.1.100", debugPort: 41737 - Separate parameters
• Natural language like "192.168.1.100:41737 and pairing: 123456 port 54321"

Requirements

• Android 11+ device with wireless debugging
• ADB installed on your computer
• Same WiFi network for both devices

Troubleshooting

"Maximum call stack size exceeded" Error

This error has been fixed in the latest version. If you still encounter it, ensure you're running the latest code.

Connection Issues

• Verify wireless debugging is enabled on your device
• Check that the IP address and port match what's shown on your device
• Make sure both devices are on the same WiFi network
• Try disabling and re-enabling wireless debugging
• Note: The wireless debugging port changes when you toggle it off/on

Pairing Issues

• Pairing codes expire quickly (usually within 2 minutes)
• Generate a fresh pairing code right before using it
• The pairing port is different from the wireless debugging port
• Once paired, you shouldn't need to pair again unless you reset connections

How it Works

The tool uses wireless ADB connections and remembers your last successful connection for convenience. Each screenshot session will:

1. Check for already connected devices first
2. If none found, try to reconnect to the last used device automatically
3. If that fails, prompt for connection details
4. Successfully connected devices are saved to ~/.android-screenshot-mcp/config.json

This means after your first successful connection, the tool can often reconnect automatically without needing the IP and port again.