scrcpy-mcp: Skill for OpenCode

scrcpy-mcp Gotchas

Coordinate systems: always use native coordinates

scrcpy_tap, scrcpy_swipe, scrcpy_long_press, and scrcpy_scroll take device-native coordinates — the same space that scrcpy_ui_dump / scrcpy_ui_find_element report in their bounds and tapX/tapY, and the same space adb shell input tap uses. So the reliable workflow needs no scaling math:

// Find the element (returns native tapX/tapY), then tap them straight through
const el = scrcpy_ui_find_element({ text: "<label>" })  // → { tapX, tapY }
scrcpy_tap({ x: el.tapX, y: el.tapY })

The input tools scale native → video-frame coordinates internally before sending the touch to the scrcpy server, so you never compute a scale factor yourself.

Don't tap screenshot pixels

scrcpy_screenshot returns a downscaled image (e.g. 576×1024 at maxSize=1024), not the native frame. Tapping a pixel coordinate read off the screenshot lands in the wrong place. Always source coordinates from ui_dump / ui_find_element (native), never from the screenshot.

Why internal scaling is required: the scrcpy server's touch protocol is not resolution-independent — the touch message's screen size must exactly match the encoder's video-frame size, or the server silently drops the event. The tools handle this conversion; you just supply native coords.

ui_find_element matching rules

The four search criteria have different matching behaviors:

Criterion	Match type	Case sensitivity
text	Partial substring (includes)	Case-insensitive
contentDesc	Partial substring (includes)	Case-insensitive
resourceId	Exact equality (===)	Case-sensitive
className	Exact equality (===)	Case-sensitive

All criteria are combined with AND logic — an element must satisfy every supplied criterion.

// text: case-insensitive substring — "bater" matches "Batería"
scrcpy_ui_find_element({ text: "bater" })  // ✓

// resourceId: exact match only — must be full string
scrcpy_ui_find_element({ resourceId: "android:id/title" })  // must match exactly

// className: full qualified name — "Button" won't match "android.widget.Button"
scrcpy_ui_find_element({ className: "android.widget.Button" })  // full name required