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_displayslist_windowsscreenshot_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 binarySCREENSHOT_MCP_OUTPUT_DIR: default output directory for screenshots
Notes
- The Swift CLI uses
CGDisplayCreateImageandCGWindowListCreateImage. - 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