| Name | mcp-server-screeny JSON |
| Version |
0.1.17
JSON |
| download |
| home_page | None |
| Summary | macOS MCP server for window enumeration and screenshot capture |
| upload_time | 2025-07-29 16:57:56 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
macos
mcp
screenshot
server
window
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://mcpx.dev/server/mcp-server-screeny)
[](https://pypi.org/project/mcp-server-screeny/)
[](https://pepy.tech/projects/mcp-server-screeny)
[](https://www.apple.com/macos/)
[](https://opensource.org/licenses/MIT)
# 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.
[](https://cursor.com/install-mcp?name=screeny&config=eyJjb21tYW5kIjoidXZ4IG1jcC1zZXJ2ZXItc2NyZWVueSJ9)
> [!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.
- 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
- **Can compress image** - if needed, compresses large images to fit within 1MB
### 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
<details>
<summary><strong>Using pipx</strong></summary>
First install with: `pipx install mcp-server-screeny`
```json
{
"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).
</details>
<details>
<summary><strong>Using uvx</strong></summary>
```json
{
"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"`).
</details>
### Cursor
1. Open Cursor settings → Tools & Integrations → MCP Tools
2. Add configuration
3. **Restart Cursor** after saving config
<details>
<summary><strong>Using pipx</strong></summary>
First install with: `pipx install mcp-server-screeny`
```json
{
"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).
</details>
<details>
<summary><strong>Using uvx</strong></summary>
```json
{
"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"`).
</details>
## 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.
<details>
<summary><strong>If using pipx</strong></summary>
```bash
# Interactive approval
mcp-server-screeny --setup
# Auto-approve all current windows
mcp-server-screeny --setup --allow-all
```
</details>
<details>
<summary><strong>If using uvx</strong></summary>
```bash
# Interactive approval
uvx mcp-server-screeny --setup
# Auto-approve all current windows
uvx mcp-server-screeny --setup --allow-all
```
</details>
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
```bash
# 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!
<details>
<summary><strong>Why I Built This</strong></summary>
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!
</details>
## Requirements
- Python 3.10+
- macOS
- Screen Capture permission
## License
MIT License
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-server-screeny",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "macos, mcp, screenshot, server, window",
"author": null,
"author_email": "Rohan Ravindran <r8ravind@uwaterloo.ca>",
"download_url": "https://files.pythonhosted.org/packages/5c/4e/bc8f1ee71e6fe6985691d065681caa946cfc44ffa4794c207445305cdaba/mcp_server_screeny-0.1.17.tar.gz",
"platform": null,
"description": "\n\n[![MCP Server](https://badge.mcpx.dev?type=server \"MCP Server\")](https://mcpx.dev/server/mcp-server-screeny)\n[](https://pypi.org/project/mcp-server-screeny/)\n[](https://pepy.tech/projects/mcp-server-screeny)\n[](https://www.apple.com/macos/)\n[](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[](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## \ud83d\udd12 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 - **Can compress image** - if needed, compresses large images to fit within 1MB\n\n### Resources\n\n- `screeny://info` - Server information and configuration details\n\n## Configuration\n\n### Claude Desktop\n\n1. Open Claude settings \u2192 Developer \u2192 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 \u2192 Tools & Integrations \u2192 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## 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## 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",
"bugtrack_url": null,
"license": "MIT",
"summary": "macOS MCP server for window enumeration and screenshot capture",
"version": "0.1.17",
"project_urls": null,
"split_keywords": [
"macos",
" mcp",
" screenshot",
" server",
" window"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "30cc48d0154051ba1d30c2ca00a4db6a4df32f2eb43617349520a60ccc139518",
"md5": "1dc4ff3f4f34e316f25e7a2db40b8af6",
"sha256": "f8529e96ec106d9cef3695c7e81812ab9590b1ebfa3b01e86397e869dc4ef47f"
},
"downloads": -1,
"filename": "mcp_server_screeny-0.1.17-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1dc4ff3f4f34e316f25e7a2db40b8af6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 12839,
"upload_time": "2025-07-29T16:57:55",
"upload_time_iso_8601": "2025-07-29T16:57:55.170404Z",
"url": "https://files.pythonhosted.org/packages/30/cc/48d0154051ba1d30c2ca00a4db6a4df32f2eb43617349520a60ccc139518/mcp_server_screeny-0.1.17-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5c4ebc8f1ee71e6fe6985691d065681caa946cfc44ffa4794c207445305cdaba",
"md5": "a0887725db5478db46e33b9c858533c8",
"sha256": "6298a2f318ac05754029ff84e4f25f1f09d3f9cc2a35c5fe71ecaf2297069ae3"
},
"downloads": -1,
"filename": "mcp_server_screeny-0.1.17.tar.gz",
"has_sig": false,
"md5_digest": "a0887725db5478db46e33b9c858533c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 941345,
"upload_time": "2025-07-29T16:57:56",
"upload_time_iso_8601": "2025-07-29T16:57:56.014489Z",
"url": "https://files.pythonhosted.org/packages/5c/4e/bc8f1ee71e6fe6985691d065681caa946cfc44ffa4794c207445305cdaba/mcp_server_screeny-0.1.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 16:57:56",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mcp-server-screeny"
}
