{"id":29279468,"url":"https://github.com/rohanrav/screeny","last_synced_at":"2026-05-06T08:32:01.515Z","repository":{"id":301433287,"uuid":"1009234932","full_name":"rohanrav/screeny","owner":"rohanrav","description":"Screeny is a privacy-focused macOS MCP server enabling AI agents to capture screenshots of user-approved windows","archived":false,"fork":false,"pushed_at":"2025-08-23T20:19:00.000Z","size":956,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-24T07:13:16.637Z","etag":null,"topics":["agents","ai","llm","macos","mcp","screenshots"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rohanrav.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-26T19:50:07.000Z","updated_at":"2025-08-23T20:19:03.000Z","dependencies_parsed_at":"2025-06-26T21:57:18.293Z","dependency_job_id":"2e69e38a-c153-4e50-a0ea-0cd2c2c1d28c","html_url":"https://github.com/rohanrav/screeny","commit_stats":null,"previous_names":["rohanrav/screeny"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/rohanrav/screeny","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohanrav%2Fscreeny","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohanrav%2Fscreeny/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohanrav%2Fscreeny/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohanrav%2Fscreeny/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rohanrav","download_url":"https://codeload.github.com/rohanrav/screeny/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohanrav%2Fscreeny/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32684621,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T02:33:58.958Z","status":"ssl_error","status_checked_at":"2026-05-06T02:33:39.611Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","llm","macos","mcp","screenshots"],"created_at":"2025-07-05T14:00:55.231Z","updated_at":"2026-05-06T08:32:01.509Z","avatar_url":"https://github.com/rohanrav.png","language":"Python","funding_links":[],"categories":["Community Servers","Other Tools and Integrations","📦 Other","MCP Servers \u0026 Protocol"],"sub_categories":["How to Submit"],"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\u0026config=eyJjb21tYW5kIjoidXZ4IG1jcC1zZXJ2ZXItc2NyZWVueSJ9)\n\n\u003e [!IMPORTANT]\n\u003e 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\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eUsing pipx\u003c/strong\u003e\u003c/summary\u003e\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\u003e **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\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eUsing uvx\u003c/strong\u003e\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"screeny\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-screeny\"]\n    }\n  }\n}\n```\n\n\u003e **Note:** If you get a \"spawn uvx ENOENT\" error, replace `\"uvx\"` with the full path to uvx:\n\u003e\n\u003e ```bash\n\u003e which uvx  # Find your uvx path\n\u003e ```\n\u003e\n\u003e Then use that full path in the config (e.g., `\"/opt/homebrew/bin/uvx\"`).\n\n\u003c/details\u003e\n\n### Cursor\n\n1. Open Cursor settings → Tools \u0026 Integrations → MCP Tools\n2. Add configuration\n3. **Restart Cursor** after saving config\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eUsing pipx\u003c/strong\u003e\u003c/summary\u003e\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\u003e **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\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eUsing uvx\u003c/strong\u003e\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"screeny\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-screeny\"]\n    }\n  }\n}\n```\n\n\u003e **Note:** If you get a \"spawn uvx ENOENT\" error, replace `\"uvx\"` with the full path to uvx:\n\u003e\n\u003e ```bash\n\u003e which uvx  # Find your uvx path\n\u003e ```\n\u003e\n\u003e Then use that full path in the config (e.g., `\"/opt/homebrew/bin/uvx\"`).\n\n\u003c/details\u003e\n\n\u003e [!NOTE] \u003e **Cursor MCP host**\n\u003e\n\u003e - Cursor auto context summarization can trigger looping tool calls (repeated screenshots).\n\u003e - 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\u003e **Note**: You need to grant Screen Capture permission to BOTH:\n\u003e\n\u003e 1. **Your Terminal application** (Terminal.app, iTerm2, etc.) - Required for running setup (can be disabled after)\n\u003e 2. **Your MCP host** (Claude Desktop, Cursor) - Required for taking screenshots\n\u003e\n\u003e To add them:\n\u003e\n\u003e 1. Open **System Settings** \u003e **Privacy \u0026 Security** \u003e **Screen \u0026 System Audio Recording**\n\u003e 2. Click the **\"+\"** button\n\u003e 3. Add your Terminal application AND your MCP host application\n\u003e 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\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eIf using pipx\u003c/strong\u003e\u003c/summary\u003e\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\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eIf using uvx\u003c/strong\u003e\u003c/summary\u003e\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\u003c/details\u003e\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 \u0026 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 \u003e Privacy \u0026 Security \u003e Screen \u0026 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\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhy I Built This\u003c/strong\u003e\u003c/summary\u003e\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\u003c/details\u003e\n\n## Requirements\n\n- Python 3.10+\n- macOS\n- Screen Capture permission\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frohanrav%2Fscreeny","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frohanrav%2Fscreeny","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frohanrav%2Fscreeny/lists"}