Screeny
Screeny MCP Server: Privacy first macOS Screenshots for AI Agents
IMPORTANT
Requires Screen Capture permission + Window Approval Setup - see instructions below.
Configuration
Claude Desktop
- Open Claude settings → Developer → Edit Config
- Add configuration
- 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
ENOENTerror, replace"mcp-server-screeny"with the full path to the executable (find it withwhich mcp-server-screenyin 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: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
Using pipx
First install with: pipx install mcp-server-screeny
{
"mcpServers": {
"screeny": {
"command": "mcp-server-screeny",
"args": []
}
}
}
Note: If you get an
ENOENTerror, replace"mcp-server-screeny"with the full path to the executable (find it withwhich mcp-server-screenyin 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:which uvx # Find your uvx pathThen use that full path in the config (e.g.,
"/opt/homebrew/bin/uvx").
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.
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.
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 --setupfirst (oruvx mcp-server-screeny --setupif 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.
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
Server Config
{
"mcpServers": {
"screeny": {
"command": "uvx",
"args": [
"mcp-server-screeny"
]
}
}
}