convez.ai
PluginAutomaçãoIntermediário
rohanrav

Screeny MCP Server

rohanrav/screeny

Captura de screenshots segura e aprovada pelo usuário para agentes de IA no macOS

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP focado em privacidade que captura screenshots de janelas pré-aprovadas no macOS para agentes de IA. Permite que assistentes tenham contexto visual de aplicações sem acessar conteúdo não autorizado, ideal para debugging e desenvolvimento.

Instalação

$npx convez-ai rohanrav/screeny

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
18
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 1 ano
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Debugging visual de aplicações durante sessões de desenvolvimento
  • Fornecer contexto visual a agentes IA para análise de UI
  • Automação de fluxos que requerem verificação visual de janelas aprovadas

Veredito

Solução sólida e bem pensada para captura de screenshots com privacidade como prioridade, usando sistema de aprovação de janelas. Limitado ao macOS, mas a arquitetura de consentimento explícito é um padrão que deveria ser mais comum em ferramentas que acessam conteúdo visual.

README

A tradução para o português deste README ainda está na fila.

Screeny Banner

MCP Server version PyPI Downloads macOS License: 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.

Install MCP Server

[!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
    • 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

  1. Open Claude settings → Developer → Edit Config
  2. Add configuration
  3. Restart Claude Desktop after saving config

First install with: pipx install mcp-server-screeny

{
  "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).

{
  "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 path

Then use that full path in the config (e.g., "/opt/homebrew/bin/uvx").

Cursor

  1. Open Cursor settings → Tools & Integrations → MCP Tools
  2. Add configuration
  3. Restart Cursor after saving config

First install with: pipx install mcp-server-screeny

{
  "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).

{
  "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 path

Then use that full path in the config (e.g., "/opt/homebrew/bin/uvx").

[!NOTE] > 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:

  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.

# Interactive approval
mcp-server-screeny --setup

# Auto-approve all current windows
mcp-server-screeny --setup --allow-all
# 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.

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

# 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!

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

Ver o original no GitHub

Bom para

Relacionados