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.
RequiresScreen 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.Only shows user approved windows
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
Open Claude settings → Developer → Edit Config
Add configuration
Restart Claude Desktop after saving config
First install with: pipx install mcp-server-screeny
Note: If you get an
ENOENT
error, replace"mcp-server-screeny"
with the full path to the executable (find it withwhich mcp-server-screeny
in your terminal).
Note: If you get a "spawn uvx ENOENT" error, replace
"uvx"
with the full path to uvx:which uvx # Find your uvx pathThen use that full path in the config (e.g.,
"/opt/homebrew/bin/uvx"
).
Cursor
Open Cursor settings → Tools & Integrations → MCP Tools
Add configuration
Restart Cursor after saving config
First install with: pipx install mcp-server-screeny
Note: If you get an
ENOENT
error, replace"mcp-server-screeny"
with the full path to the executable (find it withwhich mcp-server-screeny
in your terminal).
Note: If you get a "spawn uvx ENOENT" error, replace
"uvx"
with the full path to uvx:which uvx # Find your uvx pathThen use that full path in the config (e.g.,
"/opt/homebrew/bin/uvx"
).
>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:
Your Terminal application (Terminal.app, iTerm2, etc.) - Required for running setup (can be disabled after)
Your MCP host (Claude Desktop, Cursor) - Required for taking screenshots
To add them:
Open System Settings > Privacy & Security > Screen & System Audio Recording
Click the "+" button
Add your Terminal application AND your MCP host application
Restart both applications after granting permissions
2. Window Approval (Required)
After configuring your MCP client above, approve which windows can be captured.
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
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 (oruvx 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!
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
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A privacy-first macOS MCP server that enables AI agents to capture screenshots of pre-approved application windows for development and debugging tasks.
Related MCP Servers
- AsecurityAlicenseAqualityAn official MCP server implementation that allows AI assistants to capture website screenshots through the ScreenshotOne API, enabling visual context from web pages during conversations.Last updated -1031MIT License
- AsecurityFlicenseAqualityEnables AI tools to capture and process screenshots of a user's screen, allowing AI assistants to see and analyze what the user is looking at through a simple MCP interface.Last updated -117
- AsecurityAlicenseAqualityA server that captures screenshots from iOS Simulator using the Model Context Protocol (MCP) and saves them to a specified directory.Last updated -111MIT License
- AsecurityFlicenseAqualityAn MCP server that provides web development tools including taking screenshots of screens, enabling AI agents to capture and analyze visual content during development.Last updated -22010