Screeny MCP Server: Privacy first macOS Screenshots for AI Agents

A privacy-first, macOS-only MCP server that enables AI agents to capture screenshots of pre-approved application windows, providing secure visual context for development and debugging tasks.

> [!IMPORTANT]

> Requires Screen Capture permission + Window Approval Setup - see instructions below.

🔒 Privacy-First Design

Unlike other screenshot tools, Screeny requires explicit user approval for each window before it can be captured:

• Window approval system - Only pre-approved windows can be captured (approved during setup)
• User-controlled access - You decide exactly which windows are accessible
• Non-intrusive capture - Screenshots taken in background without changing window focus or interrupting your workflow
• No external connections - Screeny runs entirely on your device, screenshots are deleted immediately after use

Available Tools

• `listWindows` - Lists all approved application windows available for screenshot capture.

• `takeScreenshot` - Captures a screenshot of a specific window by its ID.
  • Captures windows in background - no need to bring window to front, but cannot capture minimized windows
  • Provides actual pixel data - full-fidelity image, not OCR or text extraction
  • JPEG compression with configurable cap - screenshots are always JPEG-compressed with a base64 payload cap (default preset: Medium / 250KB), configurable and clamped to 100–900KB

Resources

• `screeny://info` - Server information and configuration details

Configuration

Claude Desktop

1. Open Claude settings → Developer → Edit Config

2. Add configuration

3. Restart Claude Desktop after saving config

Using pipx

First install with: `pipx install mcp-server-screeny`

{
  "mcpServers": {
    "screeny": {
      "command": "mcp-server-screeny",
      "args": []
    }
  }
}

> Note: If you get an `ENOENT` error, replace `"mcp-server-screeny"` with the full path to the executable (find it with `which mcp-server-screeny` in your terminal).

Using uvx

{
  "mcpServers": {
    "screeny": {
      "command": "uvx",
      "args": ["mcp-server-screeny"]
    }
  }
}

> Note: If you get a "spawn uvx ENOENT" error, replace `"uvx"` with the full path to uvx:

>

> ```bash

> which uvx # Find your uvx path

> ```

>

> Then use that full path in the config (e.g., `"/opt/homebrew/bin/uvx"`).

Cursor

1. Open Cursor settings → Tools & Integrations → MCP Tools

2. Add configuration

3. Restart Cursor after saving config

Using pipx

First install with: `pipx install mcp-server-screeny`

{
  "mcpServers": {
    "screeny": {
      "command": "mcp-server-screeny",
      "args": []
    }
  }
}

> Note: If you get an `ENOENT` error, replace `"mcp-server-screeny"` with the full path to the executable (find it with `which mcp-server-screeny` in your terminal).

Using uvx

{
  "mcpServers": {
    "screeny": {
      "command": "uvx",
      "args": ["mcp-server-screeny"]
    }
  }
}

> Note: If you get a "spawn uvx ENOENT" error, replace `"uvx"` with the full path to uvx:

>

> ```bash

> which uvx # Find your uvx path

> ```

>

> Then use that full path in the config (e.g., `"/opt/homebrew/bin/uvx"`).

> [!NOTE] > Cursor MCP host

>

> - Cursor auto context summarization can trigger looping tool calls (repeated screenshots).

> - If this happens, lower the KB cap (use a smaller preset) or choose a model with a larger context window.

Setup

1. Grant Screen Capture Permission (Required)

Important: Grant permission before running window approval.

> Note: You need to grant Screen Capture permission to BOTH:

>

> 1. Your Terminal application (Terminal.app, iTerm2, etc.) - Required for running setup (can be disabled after)

> 2. Your MCP host (Claude Desktop, Cursor) - Required for taking screenshots

>

> To add them:

>

> 1. Open System Settings > Privacy & Security > Screen & System Audio Recording

> 2. Click the "+" button

> 3. Add your Terminal application AND your MCP host application

> 4. Restart both applications after granting permissions

2. Window Approval (Required)

After configuring your MCP client above, approve which windows can be captured.

If using pipx

# Interactive approval
mcp-server-screeny --setup

# Auto-approve all current windows
mcp-server-screeny --setup --allow-all

If using uvx

# Interactive approval
uvx mcp-server-screeny --setup

# Auto-approve all current windows
uvx mcp-server-screeny --setup --allow-all

Approvals are saved to `~/.screeny/approved_windows.json`. Re-run setup when you want to update the list of approved windows.

Advanced Options (Optional)

During setup, you can configure the screenshot size preset (affects stability and clarity):

• Tiny (50KB) — most stable; fine text will blur
• Small (100KB) — recommended default; balanced clarity and stability
• Medium (250KB) — more detail; may be slower and heavier
• Large (500KB) — high detail; may trigger client summarization
• XL (750KB) — maximum detail; most error-prone

Your choice is saved in `~/.screeny/config.json` as `max_b64_kb`. You can also override via the `SCREENY_MAX_B64_KB` environment variable. The active cap is clamped to 100–900KB.

Security & Privacy

• Only user-approved windows can be captured
• All processing stays local on your machine
• Screenshots are temporary and deleted immediately after use

Troubleshooting

Permission Issues

# Test window detection and permissions
mcp-server-screeny --debug

# Re-run setup if windows changed
mcp-server-screeny --setup

Common Issues

"spawn uvx ENOENT" error

• Solution: Use the full path to uvx in your MCP config instead of just `"uvx"`
• Find path with: `which uvx`
• Example: `"/opt/homebrew/bin/uvx"` or `"/usr/local/bin/uvx"`

"No approved windows found"

• Solution: Run `mcp-server-screeny --setup` first (or `uvx mcp-server-screeny --setup` if using uvx)

"Screen Recording permission required" or "No windows found"

• Solution: Grant Screen Recording permission in System Settings > Privacy & Security > Screen & System Audio Recording
  • Click "+" button and manually add your MCP host (Claude Desktop, Cursor, etc.)
  • Restart your MCP host application after granting permissions
• Try running setup again after granting permissions

Contributing

Pull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements.

This is my first MCP project - if you encounter any bugs, please open an issue and I'll do my best to fix them!

Why I Built This

I created this tool to streamline my mobile development workflow. I was tired of

manually taking screenshots repeatedly to describe UI issues. With Screeny, Cursor can directly capture screenshots of my iOS simulator and iterate on the design in a loop. I'm excited to see how others will use this!

Requirements

• Python 3.10+
• macOS
• Screen Capture permission

License

MIT License