shottr-mcp

An Effect-native MCP server that lets local agents silently capture macOS windows, displays, and exact regions, then produce Shottr-style PNGs with programmable annotations, backgrounds, padding, rounded corners, and shadows.

This is an AI-assisted project, developed collaboratively with coding agents and reviewed through automated type, integration, and image-processing tests.

Requirements

• macOS
• Node.js 22 or newer
• Shottr 1.8 or newer installed at /Applications/Shottr.app
• pnpm 11

Shottr needs Screen Recording permission. The app that launches this MCP server also needs:

• Screen Recording to enumerate windows and capture exact regions.

Grant these in System Settings → Privacy & Security, then restart the MCP host.

Install

pnpm install
pnpm build

Use the absolute path to dist/main.js in an MCP client. For Codex:

[mcp_servers.shottr]
command = "node"
args = ["/absolute/path/to/shottr-mcp/dist/main.js"]

For clients using JSON configuration:

{
  "mcpServers": {
    "shottr": {
      "command": "node",
      "args": ["/absolute/path/to/shottr-mcp/dist/main.js"]
    }
  }
}

Run shottr_doctor after connecting. It reports the installed Shottr version and any permission action still needed.

Tools

• shottr_doctor — check platform, Shottr, and window-metadata access.
• shottr_list_windows — return visible windows in front-to-back order, optionally filtered by app name or bundle ID.
• shottr_capture_window — silently capture one uniquely selected window without opening capture UI.
• shottr_capture_fullscreen — silently capture the main display without opening capture UI.
• shottr_capture_region — capture an exact macOS logical-coordinate rectangle.
• shottr_annotate_image — add pen, spotlight, measurement, and text annotations to an existing PNG.
• shottr_beautify_image — beautify an existing local image.

Capture tools always return inline PNG image content and metadata. They write a file only when given an absolute .png outputPath whose parent directory already exists.

Window selection

Use a returned window ID for the strongest targeting:

{
  "selector": { "windowId": 1234 }
}

Or select by an exact app name/bundle ID and optional case-insensitive title substring:

{
  "selector": {
    "app": "com.apple.Safari",
    "title": "Effect"
  }
}

If more than one window matches, the server returns candidates instead of guessing.

Window capture never activates an app or switches tabs. It captures only the pixels currently rendered in the selected visible window. A background browser tab cannot be captured pixel-accurately without making it visible, so agents must not focus it automatically; they should explain the limitation and wait until the user makes that tab visible.

Beautification

Before adding beautify, agents must ask the user to choose the background, padding, corner radius, and shadow settings. The server requires every choice explicitly and rejects partial styling instead of inventing visual values.

{
  "selector": { "app": "Safari" },
  "beautify": {
    "background": {
      "type": "image",
      "path": "/absolute/path/to/background.jpg"
    },
    "padding": 80,
    "cornerRadius": 20,
    "shadow": {
      "color": "#000000",
      "opacity": 0.2,
      "blur": 30,
      "offsetX": 0,
      "offsetY": 14
    }
  },
  "outputPath": "/absolute/existing/folder/safari.png"
}

Background images are center-cropped to cover. Solid and linear-gradient backgrounds are also supported:

{
  "background": {
    "type": "linearGradient",
    "from": "#7C3AED",
    "to": "#2563EB",
    "angle": 135
  },
  "padding": { "top": 48, "right": 64, "bottom": 48, "left": 64 },
  "cornerRadius": 20,
  "shadow": {
    "color": "#000000",
    "opacity": 0.2,
    "blur": 30,
    "offsetX": 0,
    "offsetY": 14
  }
}

Annotations

Capture tools accept an annotations array, and shottr_annotate_image applies the same annotations to an existing local image. Coordinates are normalized from 0 to 1 relative to the screenshot: (0, 0) is the top-left, (1, 1) is the bottom-right, and (0.5, 0.5) is the centre.

Draw a red pen stroke and place “Hello” in the centre:

{
  "annotations": [
    {
      "type": "pen",
      "points": [
        { "x": 0.1, "y": 0.2 },
        { "x": 0.3, "y": 0.1 },
        { "x": 0.5, "y": 0.2 }
      ],
      "color": "#FF0000",
      "width": 6
    },
    {
      "type": "text",
      "text": "Hello",
      "position": { "x": 0.5, "y": 0.5 },
      "color": "#FF0000",
      "fontSize": 32,
      "backgroundColor": "#FFFFFF"
    }
  ]
}

Spotlight the centre of the image:

{
  "type": "spotlight",
  "region": { "x": 0.3, "y": 0.25, "width": 0.4, "height": 0.5 },
  "shape": "ellipse",
  "dimOpacity": 0.7,
  "color": "#FFD60A",
  "width": 4
}

Measure the full width and height of a captured window:

{
  "annotations": [
    {
      "type": "measurement",
      "from": { "x": 0, "y": 0.05 },
      "to": { "x": 1, "y": 0.05 },
      "color": "#FF3B30",
      "width": 3,
      "fontSize": 24
    },
    {
      "type": "measurement",
      "from": { "x": 0.05, "y": 0 },
      "to": { "x": 0.05, "y": 1 },
      "color": "#FF3B30",
      "width": 3,
      "fontSize": 24
    }
  ]
}

Measurement labels default to the calculated image-pixel distance, such as 1440 px. The same values are returned in structured MCP metadata so agents can report dimensions without reading the pixels back from the image. Set label to override the visible text while preserving the calculated numeric result.

Behavior and privacy

Shottr exposes capture actions through URL schemes, but those actions can show capture UI and do not support headless coordinate targeting. Therefore captures use macOS screencapture for a silent agent workflow, and Shottr-style annotations and beautification are rendered locally with Sharp.

Every successful capture leaves the final PNG on the macOS clipboard, including beautified and exact-window fallback results, so it can be pasted immediately. Existing clipboard content is replaced, matching normal screenshot-tool behavior.

Images remain local. The server has no HTTP transport, upload tool, telemetry, or remote-background download support.

Development

pnpm check
pnpm test
pnpm build

Real Shottr capture is intentionally not part of the default test suite because it needs macOS permissions and captures visible user content. Run it explicitly when the current display is safe to capture:

pnpm test:e2e