Screen Capture MCP

An MCP (Model Context Protocol) server that gives AI agents eyes on your screen. Define a capture region with a visual overlay, then let your agent screenshot it on demand.

Built for Claude Code but works with any MCP-compatible client.

How It Works

Two components work together:

1. Overlay (overlay.py) — A transparent, draggable frame you position over any window. It saves the coordinates to a temp file.

2. MCP Server (server.js) — Reads those coordinates and uses macOS screencapture to grab the region, returning a base64 PNG to the agent.

┌──────────────────────────┐
│  Your App Window         │
│  ┌────────────────────┐  │
│  │ ▓▓ Overlay Frame ▓▓│  │      overlay.py
│  │ ▓                 ▓│  │   saves coordinates
│  │ ▓  (capture area) ▓│──────▶ /tmp/claude-viewport.json
│  │ ▓                 ▓│  │
│  │ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│  │
│  └────────────────────┘  │
│                          │      server.js
└──────────────────────────┘   reads coords + screencapture
                                      │
                                      ▼
                               base64 PNG → Agent

Related MCP server: MCP Screenshot Server

Tools

The MCP server exposes three tools:

Setup

Prerequisites

• macOS (uses native screencapture)

• Node.js 18+

• Python 3.8+ with Tkinter

Install

git clone https://github.com/Sherif-Aboulnasr/Screen-Capture-MCP.git
cd Screen-Capture-MCP
npm install

Configure your MCP client

Add to your MCP settings (e.g. ~/.claude/settings.json for Claude Code):

{
  "mcpServers": {
    "screen-capture": {
      "command": "node",
      "args": ["/path/to/Screen-Capture-MCP/server.js"]
    }
  }
}

Usage

1. Start the overlay

python3 overlay.py

A lime-green border frame appears on screen.

2. Position it

• Drag the top bar to move the frame over your target window

• Drag the bottom-right handle to resize

• Click the lock icon to lock the region in place (border turns red)

3. Let your agent capture

Once locked, the agent can call capture_viewport at any time to see what's on screen.

Agent: "Let me check how that looks..."
→ calls capture_viewport
→ receives screenshot of the locked region
→ "The button is misaligned — let me fix the padding..."

Capture without the overlay

Use capture_region to grab any screen coordinates directly:

{
  "x": 100,
  "y": 200,
  "width": 800,
  "height": 600
}

Overlay controls

How it's built

• Overlay: Python Tkinter — four separate edge windows with a 3px border, keeping the center click-through. A separate resize handle window at the bottom-right corner.

• Server: Node.js using @modelcontextprotocol/sdk. Reads coordinates from /tmp/claude-viewport.json, runs screencapture -R, returns base64 PNG.

• Coordinate file: JSON at /tmp/claude-viewport.json with adjusted capture coordinates and raw frame coordinates.

Use cases

• UI development — Agent captures before/after screenshots while iterating on styles

• Visual debugging — "Does this layout look right?" — agent can see for itself

• Design review — Position overlay on a Figma/design window, let the agent compare against code output

• Mobile development — Frame your iOS Simulator, let the agent see the app state

License

MIT