Screeny MCP Server for macOS Privacy Screenshots

Overview

Screeny MCP Server is a small macOS service that implements a Model Context Protocol (MCP) endpoint for privacy-safe screenshots. It enables AI agents and developer tools to request screenshots, but enforces a two-step flow: the user reviews and explicitly approves which application windows can be captured. This prevents agents from arbitrarily photographing the entire screen or capturing sensitive content without explicit consent.

The server runs locally on the user’s Mac and exposes simple endpoints to list visible windows, request screenshots, and manage approvals. It integrates into agent workflows by providing a secure, auditable permission gate between an agent’s request and the actual screen capture, making it well suited for debugging assistants, visual troubleshooting, and productivity automations that need limited visual context.

Features

• List visible windows and their metadata (title, app, bounds)
• Per-window approval workflow: user must approve a window before screenshots are allowed
• Single-shot screenshots for approved windows, returned as PNG data
• Simple HTTP API compatible with MCP-style tool integrations
• Runs locally on macOS and requests Screen Recording permission only when needed
• Minimal configuration and a single binary/server to run locally

Installation / Configuration

Prerequisites

• macOS with Screen Recording APIs (macOS 10.15+ recommended)
• git and build toolchain if building from source

Quick start (build and run)

# Clone the repo
git clone https://github.com/rohanrav/screeny.git
cd screeny

# Build (if repository includes a Makefile or build script)
make build

# Or run the bundled binary directly (replace with actual binary name)
./screeny --port 3000

Environment variables / flags

# Examples of common options
export SCREENY_PORT=3000        # HTTP port to listen on
export SCREENY_API_KEY="tok.."  # Optional API key to restrict access
./screeny --port $SCREENY_PORT --api-key $SCREENY_API_KEY

macOS permissions

• The server uses macOS screen capture APIs; the first run will usually prompt the user to grant Screen Recording permission in System Preferences → Security & Privacy → Screen Recording.
• If you run the server headless (e.g., via launchd) make sure the user session grants the permission.

Running as a background service (example)

# Basic nohup background run (replace with launchd for production)
nohup ./screeny --port 3000 > screeny.log 2>&1 &

Available Tools / API Endpoints

Typical HTTP endpoints (adjust based on the server’s actual port/config):

• GET /windows
  • Returns a list of visible windows with id, title, app name, and bounds.
• POST /approve
  • Body: { “window_id”: “” } — marks a window as approved by the user.
  • POST /screenshot
    • Body: { “window_id”: “” } — takes a screenshot of an approved window and returns PNG data or a base64 payload.
    • GET /status
      • Health/status information about the server.

    Example: list windows

    curl http://localhost:3000/windows
    # Response (JSON):
    # [
    #   {"id":"w1","app":"Safari","title":"Example — Screeny","bounds":{"x":0,"y":0,"w":1200,"h":800}},
    #   {"id":"w2","app":"Terminal","title":"bash","bounds":{...}}
    # ]
    

    Approve a window (user-driven)

    curl -X POST http://localhost:3000/approve \
      -H "Content-Type: application/json" \
      -d '{"window_id":"w1"}'
    # Response: {"approved":true,"window_id":"w1"}
    

    Capture a screenshot (only for approved windows)

    curl -X POST http://localhost:3000/screenshot \
      -H "Content-Type: application/json" \
      -d '{"window_id":"w1"}' --output window1.png
    

    You can combine these endpoints in an MCP tool manifest so an agent first requests the window list, requests user approval, and then asks the server for a screenshot.

    Use Cases

    • Debugging with context: A developer-support agent can ask the user to approve the application window showing an error dialog, then capture a screenshot of only that window to include in a bug report.
    • UI automation that respects privacy: Automation tools that need visual validation can request screenshots only for explicitly approved windows rather than the entire desktop.
    • Visual help desks: Remote assistants can guide users through UI issues by asking the user to approve the specific window to share a screenshot for diagnosis.
    • Training / annotation workflows: Collect labeled screenshots of particular app windows for training models without exposing unrelated personal content.

    Resources

    • Source code and issues: https://github.com/rohanrav/screeny
    • macOS Screen Recording permissions (Apple docs): check System Preferences → Security & Privacy → Screen Recording
    • If integrating with agents, document the tool endpoints and approval flow in your agent’s MCP tool manifest so the model prompts the user correctly before requesting screenshots.
    Tags:developer-tools