screenshot_capture

macOS

Purpose

Captures a single frame of a display, window, or region to a PNG. Returns {path, resolution (PIXELS), scale_factor, display_id} — scale_factor is the backing scale of the display that was ACTUALLY captured (the same value list_displays reports for that display_id, by construction: both read one function), so pixels = points x scale_factor when converting a coordinate from the image to ui_click. If the display could not be determined you get scale_factor_unknown instead of a guess; resolution is always there, so you can derive the ratio yourself. Requires Screen Recording permission; without it returns an explicit permission_required, never a blank image.

Required inputs

• target — What to capture. Required: {kind: "display"|"window"|"window_title"|"region"} plus display_id (see list_displays), window_id (see list_windows), title, or region {x,y,w,h} in global points.

Permissions and confirmation

No explicit confirmation parameter is exposed in this snapshot. This does not grant permission to act: obtain user authorization before any real action.

• Use only the apps, accounts and resources authorized by the user on this platform. Consult this tool's platform-specific description for its connection and permission requirements; this catalog does not assert additional OAuth scopes or OS entitlements.

{
  "properties": {
    "output_path": {
      "description": "Where to write the PNG (default: temp file). Missing parent folders are created.",
      "type": "string"
    },
    "target": {
      "description": "What to capture. Required: {kind: \"display\"|\"window\"|\"window_title\"|\"region\"} plus display_id (see list_displays), window_id (see list_windows), title, or region {x,y,w,h} in global points.",
      "properties": {
        "display_id": {
          "type": "string"
        },
        "kind": {
          "enum": [
            "display",
            "window",
            "window_title",
            "region"
          ],
          "type": "string"
        },
        "region": {
          "description": "{x,y,w,h} global points.",
          "type": "object"
        },
        "title": {
          "description": "Exact window title to capture (kind:\"window_title\"). Enumerates ALL windows directly — including overlays/panels like Notification Center that list_windows hides unless include_overlays:true. If more than one window has this title, the frontmost one is captured and the response reports matched_windows > 1.",
          "type": "string"
        },
        "window_id": {
          "type": "string"
        }
      },
      "required": [
        "kind"
      ],
      "type": "object"
    }
  },
  "required": [
    "target"
  ],
  "type": "object"
}

Documentation example

Do not execute this example. These concrete inputs refer to a fictional demonstration dataset. Resolve real handles and obtain user authorization before any real call.

{
  "target": {
    "display_id": "1",
    "kind": "display"
  }
}