{"id":"f988dac9-2679-4fa9-9423-994fa1e340c0","slug":"rohanrav-screeny","kind":"mcp","name":"screeny","summary":"Screeny is a privacy-focused macOS MCP server enabling AI agents to capture screenshots of user-approved windows","owner":"rohanrav","repoUrl":"https://github.com/rohanrav/screeny","license":"MIT","licenseTier":"permissive","trust":"community","stars":16,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-06-26T19:50:07.000Z","addedAt":"2026-10-14T05:18:14.393Z","logoUrl":"https://avatars.githubusercontent.com/u/25865718?u=c4c198ae2fc1e03d74e6aa51a8c26d813a58202d&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra"],"tags":["macos","agents","ai","llm","screenshots"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-17T23:12:53.357Z","sample":false,"url":"https://conduits.dev/tools/rohanrav-screeny","language":"Python","transports":["stdio"],"install":{"pypi":"mcp-server-screeny"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"![Screeny Banner](screeny_banner.png)\n\n[![MCP Server](https://badge.mcpx.dev?type=server \"MCP Server\")](https://mcpx.dev/server/mcp-server-screeny)\n[![version](https://badge.fury.io/py/mcp-server-screeny.svg)](https://pypi.org/project/mcp-server-screeny/)\n[![PyPI Downloads](https://static.pepy.tech/badge/mcp-server-screeny)](https://pepy.tech/projects/mcp-server-screeny)\n[![macOS](https://img.shields.io/badge/macOS-only-blue.svg)](https://www.apple.com/macos/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n# Screeny MCP Server: Privacy first macOS Screenshots for AI Agents\n\nA **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.\n\n[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=screeny&config=eyJjb21tYW5kIjoidXZ4IG1jcC1zZXJ2ZXItc2NyZWVueSJ9)\n\n> [!IMPORTANT]\n> Requires **Screen Capture permission** + **Window Approval Setup** - see instructions below.\n\n## 🔒 Privacy-First Design\n\nUnlike other screenshot tools, Screeny requires **explicit user approval** for each window before it can be captured:\n\n- **Window approval system** - Only pre-approved windows can be captured (approved during setup)\n- **User-controlled access** - You decide exactly which windows are accessible\n- **Non-intrusive capture** - Screenshots taken in background without changing window focus or interrupting your workflow\n- **No external connections** - Screeny runs entirely on your device, screenshots are deleted immediately after use\n\n## Available Tools\n\n- `listWindows` - Lists all approved application windows available for screenshot capture.\n\n  - Only shows user approved windows\n\n- `takeScreenshot` - Captures a screenshot of a specific window by its ID.\n  - **Captures windows in background** - no need to bring window to front, but cannot capture minimized windows\n  - **Provides actual pixel data** - full-fidelity image, not OCR or text extraction\n  - **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**\n\n### Resources\n\n- `screeny://info` - Server information and configuration details\n\n## Configuration\n\n### Claude Desktop\n\n1. Open Claude settings → Developer → Edit Config\n2. Add configuration\n3. **Restart Claude Desktop** after saving config\n\n<details>\n<summary><strong>Using pipx</strong></summary>\n\nFirst install with: `pipx install mcp-server-screeny`\n\n```json\n{\n  \"mcpServers\": {\n    \"screeny\": {\n      \"command\": \"mcp-server-screeny\",\n      \"args\": []\n    }\n  }\n}\n```\n\n> **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).\n\n</details>\n\n<details>\n<summary><strong>Using uvx</strong></summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"screeny\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-screeny\"]\n    }\n  }\n}\n```\n\n> **Note:** If you get a \"spawn uvx ENOENT\" error, replace `\"uvx\"` with the full path to uvx:\n>\n> ```bash\n> which uvx  # Find your uvx path\n> ```\n>\n> Then use that full path in the config (e.g., `\"/opt/homebrew/bin/uvx\"`).\n\n</details>\n\n### Cursor\n\n1. Open Cursor settings → Tools & Integrations → MCP Tools\n2. Add configuration\n3. **Restart Cursor** after saving config\n\n<details>\n<summary><strong>Using pipx</strong></summary>\n\nFirst install with: `pipx install mcp-server-screeny`\n\n```json\n{\n  \"mcpServers\": {\n    \"screeny\": {\n      \"command\": \"mcp-server-screeny\",\n      \"args\": []\n    }\n  }\n}\n```\n\n> **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).\n\n</details>\n\n<details>\n<summary><strong>Using uvx</strong></summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"screeny\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-screeny\"]\n    }\n  }\n}\n```\n\n> **Note:** If you get a \"spawn uvx ENOENT\" error, replace `\"uvx\"` with the full path to uvx:\n>\n> ```bash\n> which uvx  # Find your uvx path\n> ```\n>\n> Then use that full path in the config (e.g., `\"/opt/homebrew/bin/uvx\"`).\n\n</details>\n\n> [!NOTE] > **Cursor MCP host**\n>\n> - Cursor auto context summarization can trigger looping tool calls (repeated screenshots).\n> - If this happens, lower the KB cap (use a smaller preset) or choose a model with a larger context window.\n\n## Setup\n\n### 1. Grant Screen Capture Permission (Required)\n\n**Important:** Grant permission before running window approval.\n\n> **Note**: You need to grant Screen Capture permission to BOTH:\n>\n> 1. **Your Terminal application** (Terminal.app, iTerm2, etc.) - Required for running setup (can be disabled after)\n> 2. **Your MCP host** (Claude Desktop, Cursor) - Required for taking screenshots\n>\n> To add them:\n>\n> 1. Open **System Settings** > **Privacy & Security** > **Screen & System Audio Recording**\n> 2. Click the **\"+\"** button\n> 3. Add your Terminal application AND your MCP host application\n> 4. **Restart both applications** after granting permissions\n\n### 2. Window Approval (Required)\n\nAfter configuring your MCP client above, approve which windows can be captured.\n\n<details>\n<summary><strong>If using pipx</strong></summary>\n\n```bash\n# Interactive approval\nmcp-server-screeny --setup\n\n# Auto-approve all current windows\nmcp-server-screeny --setup --allow-all\n```\n\n</details>\n\n<details>\n<summary><strong>If using uvx</strong></summary>\n\n```bash\n# Interactive approval\nuvx mcp-server-screeny --setup\n\n# Auto-approve all current windows\nuvx mcp-server-screeny --setup --allow-all\n```\n\n</details>\n\nApprovals are saved to `~/.screeny/approved_windows.json`. Re-run setup when you want to update the list of approved windows.\n\n### Advanced Options (Optional)\n\nDuring setup, you can configure the screenshot size preset (affects stability and clarity):\n\n- **Tiny (50KB)** — most stable; fine text will blur\n- **Small (100KB)** — recommended default; balanced clarity and stability\n- **Medium (250KB)** — more detail; may be slower and heavier\n- **Large (500KB)** — high detail; may trigger client summarization\n- **XL (750KB)** — maximum detail; most error-prone\n\nYour 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**.\n\n## Security & Privacy\n\n- Only user-approved windows can be captured\n- All processing stays local on your machine\n- Screenshots are temporary and deleted immediately after use\n\n## Troubleshooting\n\n### Permission Issues\n\n```bash\n# Test window detection and permissions\nmcp-server-screeny --debug\n\n# Re-run setup if windows changed\nmcp-server-screeny --setup\n```\n\n### Common Issues\n\n**\"spawn uvx ENOENT\" error**\n\n- Solution: Use the full path to uvx in your MCP config instead of just `\"uvx\"`\n- Find path with: `which uvx`\n- Example: `\"/opt/homebrew/bin/uvx\"` or `\"/usr/local/bin/uvx\"`\n\n**\"No approved windows found\"**\n\n- Solution: Run `mcp-server-screeny --setup` first (or `uvx mcp-server-screeny --setup` if using uvx)\n\n**\"Screen Recording permission required\" or \"No windows found\"**\n\n- Solution: Grant Screen Recording permission in System Settings > Privacy & Security > Screen & System Audio Recording\n  - Click \"+\" button and manually add your MCP host (Claude Desktop, Cursor, etc.)\n  - Restart your MCP host application after granting permissions\n- Try running setup again after granting permissions\n\n## Contributing\n\nPull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements.\n\nThis is my first MCP project - if you encounter any bugs, please open an issue and I'll do my best to fix them!\n\n<details>\n<summary><strong>Why I Built This</strong></summary>\n\nI created this tool to streamline my mobile development workflow. I was tired of\nmanually 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!\n\n</details>\n\n## Requirements\n\n- Python 3.10+\n- macOS\n- Screen Capture permission\n\n## License\n\nMIT License\n"}