Screenshot MCP (macOS)

Minimal MCP server for macOS screenshots with a Swift CLI backend. Supports:

• display screenshots

• window screenshots

• window recording (duration or start/stop)

• listing displays/windows

Requirements

• macOS 12+ (CoreGraphics APIs)

• Swift (Xcode CLI tools)

• Node.js 18+

• Screen Recording permission granted to the terminal or host app

Quickstart

SwiftUI UI (no Xcode)

Debug logs

The SwiftUI app writes logs to ~/Documents/screenshot_mcp/debug.log by default.

MCP Tools

• list_displays

• list_windows

• screenshot_display { display_id, output_path? }

• screenshot_window { window_id, output_path? }

• record_window_duration { window_id, duration_seconds, fps?, system_audio?, output_path? }

• record_window_start { window_id, fps?, system_audio?, output_path? }

• record_window_stop { recording_id }

CLI Usage

Configuration

• SCREENSHOT_MCP_BIN: path to the compiled Swift binary

• SCREENSHOT_MCP_OUTPUT_DIR: default output directory for screenshots

Notes

• The Swift CLI uses CGDisplayCreateImage and CGWindowListCreateImage.

• Window recording samples window frames (default 10 fps) and writes MP4 via AVAssetWriter.

• System audio capture requires macOS 13+ and records all system audio, not just the window.

• If screenshots are blank, ensure Screen Recording permission is granted.

License

MIT