Provides complete vision and control over Android devices, including real-time screen streaming, UI automation with element detection, input control (tap, swipe, text entry), app management, shell command execution, file transfer, and clipboard access. Supports both USB and WiFi connections with multiple simultaneous devices.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Scrcpy Visiontake a screenshot of my phone's home screen"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-scrcpy-vision
An MCP server that gives AI agents complete vision and control over Android devices.
Features:
Real-time Vision: Continuous screen streaming via scrcpy H.264 + ffmpeg
Fast Input Control: When streaming, input uses scrcpy control protocol (~5-10ms latency vs ~100-300ms with adb shell)
UI Automation: Element detection via uiautomator with tap coordinates
Full Input Control: Tap, swipe, long press, pinch, drag-drop, text, keycodes
System Access: Shell commands, file transfer, clipboard, notifications
Multi-device: Control multiple Android devices simultaneously
WiFi ADB: Connect wirelessly for untethered automation
Quick Start
1. Prerequisites
Required:
Node.js 18+
ADB (Android Platform Tools) in PATH
Android device with USB debugging enabled
For streaming (recommended for fast input):
2. Install
3. Configure
Create .env file:
4. Add to MCP Client
Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows):
Cursor (Settings > MCP):
5. Connect Device
Enable USB debugging on Android device (Settings > Developer Options > USB Debugging)
Connect via USB
Accept RSA fingerprint prompt on device
Verify:
adb devicesshould show your device
How It Works
Two Modes of Operation
1. Snapshot Mode (No streaming required)
Uses
android.vision.snapshotfor screenshotsInput uses ADB shell commands (~100-300ms per action)
Works without scrcpy/ffmpeg
Best for simple automation or when streaming isn't available
2. Streaming Mode (Recommended)
Start with
android.vision.startStreamContinuous JPEG frames available via resource URI
Input uses scrcpy control protocol (~5-10ms per action)
10-20x faster than snapshot mode
Best for real-time control and rapid interactions
Performance Comparison
Operation | Snapshot Mode | Streaming Mode |
Tap | ~100-300ms | ~5-10ms |
Swipe | ~300-500ms | ~50-100ms |
Type text | ~50ms/char | ~5ms total |
Screenshot | ~500ms | ~33ms (30fps) |
Tools Reference (32 tools)
Device Management
Tool | Parameters | Description |
| - | List connected devices |
|
| Get device info (model, SDK, etc.) |
|
| Enable WiFi debugging |
|
| Get device WiFi IP |
|
| Connect via WiFi |
|
| Disconnect WiFi |
Vision
Tool | Parameters | Description |
|
| Start continuous stream (enables fast input) |
|
| Stop stream |
|
| Take PNG screenshot (works without streaming) |
|
| Get UI hierarchy XML |
|
| Find elements with tap coords |
Input Control
Note: These automatically use fast scrcpy control when streaming, otherwise fall back to ADB.
Tool | Parameters | Description |
|
| Tap at coordinates |
|
| Swipe gesture |
|
| Long press |
|
| Pinch zoom |
|
| Drag and drop |
|
| Type text |
|
| Send keycode |
App Control
Tool | Parameters | Description |
|
| Launch app |
|
| Force-stop app |
|
| List installed apps |
|
| Get foreground activity |
System
Tool | Parameters | Description |
|
| Execute shell command |
|
| Push file to device |
|
| Pull file from device |
|
| List directory |
|
| Get clipboard |
|
| Set clipboard |
|
| Get notifications |
Screen Control
Tool | Parameters | Description |
|
| Wake screen |
|
| Sleep screen |
|
| Check if screen is on |
|
| Unlock (unsecured only) |
Resources
The server exposes these MCP resources:
android://devices- JSON list of connected devicesandroid://device/<serial>/frame/latest.jpg- Latest JPEG frame (when streaming)
Usage Examples
Basic Automation Loop (Streaming Mode)
Simple Screenshot Mode
WiFi Connection Workflow
App Testing Example
Common Keycodes
Key | Code | Key | Code |
HOME | 3 | BACK | 4 |
VOLUME_UP | 24 | VOLUME_DOWN | 25 |
POWER | 26 | ENTER | 66 |
DELETE | 67 | TAB | 61 |
MENU | 82 | APP_SWITCH | 187 |
WAKEUP | 224 | SLEEP | 223 |
Troubleshooting
No devices found
Ensure USB debugging is enabled and RSA fingerprint accepted.
Scrcpy version mismatch
SCRCPY_SERVER_VERSION must exactly match your scrcpy-server file. Check the scrcpy release version you downloaded.
ffmpeg not found
Windows: Download from https://ffmpeg.org/download.html, extract, add bin folder to PATH
macOS:
brew install ffmpegLinux:
apt install ffmpegoryum install ffmpeg
Or set FFMPEG_PATH in .env to the full path.
uiautomator dump fails
Some devices need screen on. Try android.screen.wake first.
Clipboard not working (Android 10+)
Android 10+ restricts clipboard access. Use UI automation to paste instead.
Stream won't start
Check scrcpy-server path is correct
Verify version numbers match
Try running scrcpy standalone first to verify it works
Notes & Limitations
Fast input when streaming: When a stream is active, tap/swipe/text/keyevent use the scrcpy control protocol (~5-10ms latency). Without streaming, falls back to
adb shell input(~100-300ms).One stream per device at a time
Snapshot works without scrcpy - useful fallback when streaming is not needed
Clipboard has platform limitations on Android 10+
Notifications may require permissions on newer Android
Pinch gesture currently simulates single-finger; true multi-touch requires the streaming session
Security Warning
This MCP server provides full control over connected Android devices:
Execute arbitrary shell commands
Read/write files on device
Control UI and input
Access clipboard and notifications
Only connect devices you own and trust the AI agent.
Development
See claude.md for developer documentation. See agents.md for AI agent integration guide.
License
MIT
This server cannot be installed