Screenshots
See the screen: JSON with a base64 image, raw image bytes, or a zoomed region.
Take a screenshot
Needs the read permission. Answers within 5 s.
Captures the desktop now, scaled to 1280x720 by default, and returns JSON: base64 image plus its id, size and input_seq. Add region to zoom. For raw bytes (curl, <img>) use getScreenshotImage. A copy is saved in the screen's history unless detailed history is off; the reply itself is Cache-Control: no-store.
path Parameters
screen_id^scr_[0-9a-z]{20}$ · requiredScreen id (scr_...).
query Parameters
size^([0-9]{2,4}x[0-9]{2…Image size, WIDTHxHEIGHT or full.
WIDTHxHEIGHT with the desktop's aspect ratio, or full (desktop size).
formatpng (default), webp or jpeg.
png by default (lossless, sharp text, no ICC chunk). webp at quality 80 is what the hosted MCP server sends, because it is smaller. jpeg is not recommended for UI text.
qualitywebp and jpeg quality, 1 to 100.
max_bytesCap on the encoded image: quality steps down, then the image shrinks.
Cap on the encoded image. webp and jpeg step quality 80, 70, 60, 50, then shrink; png only shrinks. The reply says the quality and size used. The hosted MCP sends 105000.
region^[0-9]{1,4},[0-9]{1,…Zoom: x0,y0,x1,y1 in the units of the screenshot named by screenshot_id (else 1280x720). Returned at full resolution.
screenshot_id^shot_[0-9a-z]{20}$With region: the screenshot whose size the region is measured in.
max_upscale^(fit|[1-8](\.[0-9])…With region: fit (default) or a number such as 2 to cap the upscale.
cursorDraw the pointer.
settletrue: wait until the screen is quiet (300 ms, 2 s cap) before capturing. Default: capture now.
windowstrue: also list the open windows (title, app, place, which is active) in windows.
Headers
Kubi-Run^[ -~]{1,100}$Optional label that groups calls into one run in the screen's history. It is only a label and never locks the screen. The SDK fills it from KUBI_RUN, else Claude Code's CLAUDE_CODE_SESSION_ID, else one id per client it creates.
Take a screenshot › Responses
Success.
screenshot_id^shot_[0-9a-z]{20}$ · requiredNames one capture. Pass it to runActions (and to getScreenshot with region) so coordinates use its size and stale views are refused.
widthheightscreen_widthscreen_heightcaptured_atinput_seqInput actions run on this screen before the capture. runActions with this screenshot_id refuses to run if it has moved on.
size_bytesEncoded image size before base64.
dataThe image, base64. A copy is saved in the screen's history unless detailed history is off.
With windows=true: the open windows, topmost first, in this screenshot's pixels (a region's: the full screenshot's). Normal windows and dialogs only; at most 50.
Take a screenshot (image bytes)
Needs the read permission. Answers within 5 s.
The same capture as getScreenshot, returned as image bytes with the metadata in headers. For curl, <img> tags and scripts that save files.
path Parameters
screen_id^scr_[0-9a-z]{20}$ · requiredScreen id (scr_...).
query Parameters
size^([0-9]{2,4}x[0-9]{2…Image size, WIDTHxHEIGHT or full.
WIDTHxHEIGHT with the desktop's aspect ratio, or full (desktop size).
formatpng (default), webp or jpeg.
png by default (lossless, sharp text, no ICC chunk). webp at quality 80 is what the hosted MCP server sends, because it is smaller. jpeg is not recommended for UI text.
qualitywebp and jpeg quality, 1 to 100.
max_bytesCap on the encoded image: quality steps down, then the image shrinks.
Cap on the encoded image. webp and jpeg step quality 80, 70, 60, 50, then shrink; png only shrinks. The reply says the quality and size used. The hosted MCP sends 105000.
region^[0-9]{1,4},[0-9]{1,…Zoom: x0,y0,x1,y1 in the units of the screenshot named by screenshot_id (else 1280x720). Returned at full resolution.
screenshot_id^shot_[0-9a-z]{20}$With region: the screenshot whose size the region is measured in.
max_upscale^(fit|[1-8](\.[0-9])…With region: fit (default) or a number such as 2 to cap the upscale.
cursorDraw the pointer.
settletrue: wait until the screen is quiet (300 ms, 2 s cap) before capturing. Default: capture now.
Headers
Kubi-Run^[ -~]{1,100}$Optional label that groups calls into one run in the screen's history. It is only a label and never locks the screen. The SDK fills it from KUBI_RUN, else Claude Code's CLAUDE_CODE_SESSION_ID, else one id per client it creates.
Take a screenshot (image bytes) › Responses
Success.