Screeny

Screeny MCP Server: Capturas de tela macOS com foco em privacidade para Agentes de IA

Um servidor MCP exclusivo para macOS, com foco em privacidade, que permite que agentes de IA capturem capturas de tela de janelas de aplicativos pré-aprovadas, fornecendo contexto visual seguro para tarefas de desenvolvimento e depuração.

[!IMPORTANT] Requer permissão de Captura de Tela + Configuração de Aprovação de Janelas - veja as instruções abaixo.

🔒 Design com Foco em Privacidade

Diferente de outras ferramentas de captura de tela, o Screeny exige aprovação explícita do usuário para cada janela antes que ela possa ser capturada:

• Sistema de aprovação de janelas - Somente janelas pré-aprovadas podem ser capturadas (aprovadas durante a configuração)
• Acesso controlado pelo usuário - Você decide exatamente quais janelas são acessíveis
• Captura não intrusiva - Capturas de tela feitas em segundo plano sem alterar o foco da janela ou interromper seu fluxo de trabalho
• Sem conexões externas - O Screeny roda inteiramente no seu dispositivo, e as capturas de tela são excluídas imediatamente após o uso

Ferramentas Disponíveis

• listWindows - Lista todas as janelas de aplicativos aprovadas disponíveis para captura de tela.

  • Mostra apenas janelas aprovadas pelo usuário

• takeScreenshot - Captura uma captura de tela de uma janela específica pelo seu ID.

  • Captura janelas em segundo plano - não é necessário trazer a janela para frente, mas não é possível capturar janelas minimizadas
  • Fornece dados reais de pixels - imagem com fidelidade total, não OCR ou extração de texto
  • Compressão JPEG com limite configurável - as capturas de tela são sempre comprimidas em JPEG com um limite de payload base64 (predefinição padrão: Médio / 250KB), configurável e limitado a 100–900KB

Recursos

• screeny://info - Informações do servidor e detalhes de configuração

Configuração

Claude Desktop

1. Abra as configurações do Claude → Developer → Edit Config
2. Adicione a configuração
3. Reinicie o Claude Desktop após salvar a configuração

{
  "mcpServers": {
    "screeny": {
      "command": "mcp-server-screeny",
      "args": []
    }
  }
}

{
  "mcpServers": {
    "screeny": {
      "command": "uvx",
      "args": ["mcp-server-screeny"]
    }
  }
}

Cursor

1. Abra as configurações do Cursor → Tools & Integrations → MCP Tools
2. Adicione a configuração
3. Reinicie o Cursor após salvar a configuração

{
  "mcpServers": {
    "screeny": {
      "command": "mcp-server-screeny",
      "args": []
    }
  }
}

{
  "mcpServers": {
    "screeny": {
      "command": "uvx",
      "args": ["mcp-server-screeny"]
    }
  }
}

[!NOTE] > Cursor MCP host

• A sumarização automática de contexto do Cursor pode acionar chamadas de ferramentas em loop (capturas de tela repetidas).
• Se isso acontecer, reduza o limite de KB (use uma predefinição menor) ou escolha um modelo com uma janela de contexto maior.

Configuração

1. Conceda a Permissão de Captura de Tela (Obrigatório)

Importante: Conceda a permissão antes de executar a aprovação de janelas.

Nota: Você precisa conceder a permissão de Captura de Tela a AMBOS:

1. Seu aplicativo de Terminal (Terminal.app, iTerm2, etc.) - Necessário para executar a configuração (pode ser desativado depois)
2. Seu host MCP (Claude Desktop, Cursor) - Necessário para tirar capturas de tela

Para adicioná-los:

1. Abra Ajustes do Sistema > Privacidade e Segurança > Gravação de Tela e Áudio do Sistema
2. Clique no botão "+"
3. Adicione seu aplicativo de Terminal E seu aplicativo host MCP
4. Reinicie ambos os aplicativos após conceder as permissões

2. Aprovação de Janelas (Obrigatório)

Após configurar seu cliente MCP acima, aprove quais janelas podem ser capturadas.

# 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

As aprovações são salvas em ~/.screeny/approved_windows.json. Execute a configuração novamente quando quiser atualizar a lista de janelas aprovadas.

Opções Avançadas (Opcional)

Durante a configuração, você pode configurar a predefinição de tamanho da captura de tela (afeta estabilidade e clareza):

• Pequeno (50KB) — mais estável; texto fino ficará desfocado
• Menor (100KB) — padrão recomendado; clareza e estabilidade equilibradas
• Médio (250KB) — mais detalhes; pode ser mais lento e pesado
• Grande (500KB) — alto detalhe; pode acionar a sumarização do cliente
• Extra Grande (750KB) — detalhe máximo; mais propenso a erros

Sua escolha é salva em ~/.screeny/config.json como max_b64_kb. Você também pode substituí-la pela variável de ambiente SCREENY_MAX_B64_KB. O limite ativo é restrito a 100–900KB.

Segurança e Privacidade

• Somente janelas aprovadas pelo usuário podem ser capturadas
• Todo o processamento permanece local na sua máquina
• As capturas de tela são temporárias e excluídas imediatamente após o uso

Solução de Problemas

Problemas de Permissão

# Test window detection and permissions
mcp-server-screeny --debug

# Re-run setup if windows changed
mcp-server-screeny --setup

Problemas Comuns

Erro "spawn uvx ENOENT"

• Solução: Use o caminho completo para uvx na sua configuração MCP em vez de apenas "uvx"
• Encontre o caminho com: which uvx
• Exemplo: "/opt/homebrew/bin/uvx" ou "/usr/local/bin/uvx"

"Nenhuma janela aprovada encontrada"

• Solução: Execute mcp-server-screeny --setup primeiro (ou uvx mcp-server-screeny --setup se estiver usando uvx)

"Permissão de Gravação de Tela necessária" ou "Nenhuma janela encontrada"

• Solução: Conceda a permissão de Gravação de Tela em Ajustes do Sistema > Privacidade e Segurança > Gravação de Tela e Áudio do Sistema
  • Clique no botão "+" e adicione manualmente seu host MCP (Claude Desktop, Cursor, etc.)
  • Reinicie seu aplicativo host MCP após conceder as permissões
• Tente executar a configuração novamente após conceder as permissões

Contribuindo

Pull requests são bem-vindos! Sinta-se à vontade para contribuir com novas ideias, correções de bugs ou melhorias.

Este é meu primeiro projeto MCP - se você encontrar algum bug, por favor abra uma issue e farei o meu melhor para corrigi-los!

Requisitos

• Python 3.10+
• macOS
• Permissão de Captura de Tela

Licença

Licença MIT