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

npm install
swift build
node server.js

SwiftUI UI (no Xcode)

swift build
swift run screenshot_mcp_app

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

swift run screenshot_mcp list-displays
swift run screenshot_mcp list-windows
swift run screenshot_mcp screenshot-display <display_id> ./captures/display.png
swift run screenshot_mcp screenshot-window <window_id> ./captures/window.png
swift run screenshot_mcp record-window-duration <window_id> ./captures/window.mp4 5 10 true
swift run screenshot_mcp record-window-start <window_id> ./captures/window.mp4 10 true
# stop with Ctrl+C or SIGINT

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