Screen Agent
Agente de Pantalla
Agente de pruebas nativo de IA que ve su aplicación como un usuario real: 15 veces más rápido que Claude Code, sin tocar su pantalla.
Un servidor MCP para pruebas visuales autónomas. La IA planifica los pasos de la prueba en lenguaje natural, el servidor los ejecuta todos sin viajes de ida y vuelta al LLM. Funciona en segundo plano a través de CDP (Chrome) o la API de Accesibilidad (aplicaciones nativas).
Demo Rápida
# The AI plans. The server executes. No LLM round-trips. Background. 3 seconds.
run_test(name="Login Flow", steps=[
{"find": "Email", "action": "click_and_type", "text": "user@test.com"},
{"find": "Password", "action": "click_and_type", "text": "secret123"},
{"find": "Log in", "action": "click"},
{"verify": "Dashboard"},
])
# → ✅ 4/4 passed in 800ms. Screenshot evidence attached.Related MCP server: Open Computer Use
¿Por qué?
Cada herramienta de pruebas le obliga a elegir: rápida pero frágil (Playwright) o inteligente pero lenta (uso de computadora de Claude Code). El Agente de Pantalla es ambas cosas:
Ejecución Autónoma —
run_test()ejecuta TODOS los pasos en el lado del servidor. Sin viajes de ida y vuelta al LLM. 150ms/paso frente a los 1-3s/paso de Claude Code. 15 veces más rápido.Visión Primero — el LLM VE la pantalla y decide dónde hacer clic. No usa selectores DOM. Los cambios en la interfaz de usuario no rompen las pruebas porque el LLM reinterpreta la pantalla.
act+eval_js—actdevuelve una captura de pantalla para que el LLM la analice visualmente, luego ejecuta en las coordenadas proporcionadas por el LLM.eval_jsejecuta JavaScript a través de CDP para aserciones. 5 pruebas en 0.6s.Pruebas en Segundo Plano —
window_scope+ CDP le permite probar aplicaciones de Chrome en cualquier Espacio de macOS sin tocar la pantalla del usuario. Para aplicaciones nativas, prueba detrás de otras ventanas en el mismo Espacio.Cadena de Entrada Multi-Backend — tres métodos de entrada (API de Accesibilidad → CGEvent → pyautogui) con respaldo automático. Funciona con aplicaciones nativas, aplicaciones Electron y motores de juegos.
Guardián de Entrada — sistema de seguridad en tiempo real que pausa todas las acciones del agente cuando toca el ratón o el teclado. Ninguna otra herramienta ofrece esto.
Flujos de Trabajo entre Aplicaciones — flujos de prueba que abarcan múltiples aplicaciones (correo electrónico → navegador → Slack). Ninguna otra herramienta puede hacer esto porque todas son de una sola aplicación.
Arquitectura
┌──────────────────────────────────┐
│ MCP Layer │ 22 tools via Model Context Protocol
├──────────────────────────────────┤
│ Engine Layer │ InputChain (fallback) + Guardian (safety)
│ │ + WindowSession (background testing)
├──────────────────────────────────┤
│ Platform Layer │ Protocol-based backends
│ AX → CGEvent → pyautogui │ macOS / Windows / Linux
└──────────────────────────────────┘Cadena de Backend de Entrada
El desafío de diseño central: pyautogui funciona para aproximadamente el 80% de las aplicaciones, pero falla en motores de juegos y muchas aplicaciones Electron. El Agente de Pantalla resuelve esto con un patrón de Cadena de Responsabilidad:
Prioridad | Backend | Método | Mejor para |
1 | AX |
| Aplicaciones nativas de macOS — semántico, no requiere coordenadas |
2 | CGEvent |
| Juegos, Electron — inyección de eventos nativos del SO |
3 | pyautogui | Envoltorio de Python | Respaldo multiplataforma |
Cada backend implementa el mismo protocolo InputBackend. Si uno falla, la cadena intenta automáticamente el siguiente. Todos los intentos se registran con telemetría para la observabilidad.
Instalación
pip install screen-agent
# Recommended: install macOS native backends
pip install screen-agent[macos]Inicio Rápido
Con Claude Code
claude mcp add screen -- screen-agent serveCon Cursor / otros clientes MCP
Añadir a su configuración de MCP:
{
"mcpServers": {
"screen": {
"command": "screen-agent",
"args": ["serve"]
}
}
}Comprobar capacidades del sistema
screen-agent checkHerramientas
Percepción
Herramienta | Descripción |
| Captura de pantalla (completa o región), devuelve imagen para análisis visual |
| Lista todas las ventanas visibles con posiciones |
| Ventana enfocada actualmente |
| Posición actual del ratón |
Entrada (todas admiten verify: true para capturas de pantalla post-acción)
Herramienta | Descripción |
| Clic en coordenadas (izquierdo/derecho/medio, clic múltiple) |
| Escribir texto en el cursor (Unicode mediante portapapeles en macOS) |
| Pulsación de tecla con modificadores (ej. Cmd+C) |
| Rueda de desplazamiento en posición opcional |
| Mover cursor sin hacer clic |
| Arrastrar entre dos puntos |
| Traer ventana al frente por coincidencia parcial de título |
OCR (detecta automáticamente chino, japonés, coreano, inglés)
Herramienta | Descripción |
| Extraer todo el texto con cuadros delimitadores |
| Encontrar texto y devolver ubicación |
| Encontrar texto y hacer clic en su centro |
Pruebas Autónomas (el diferenciador)
Herramienta | Descripción |
| Ejecutar un plan de prueba completo de forma autónoma — sin viajes de ida y vuelta al LLM. 15 veces más rápido. |
| Visión primero: devuelve captura de pantalla → el LLM mira → ejecuta en coordenadas |
| Ejecutar JavaScript a través de CDP. Aserciones DOM, clics en elementos, comprobaciones de estado |
| Basado en OCR: encontrar elemento por texto + clic/escribir en una sola llamada |
Pruebas en Segundo Plano
Herramienta | Descripción |
| Bloquear a una ventana. Chrome: CDP automático (cualquier Espacio). Nativo: CGWindowList (mismo Espacio). |
| Liberar alcance de ventana, volver al modo de pantalla completa |
Pruebas Visuales E2E
Herramienta | Descripción |
| Iniciar una sesión de prueba con recolección automática de capturas de pantalla |
| Comenzar un paso de prueba (captura automáticamente la captura de pantalla "antes") |
| Verificar paso mediante comprobación de texto OCR o diferencia de captura de pantalla |
| Finalizar sesión, generar informe markdown con evidencia |
| Estado actual de la sesión |
Seguridad (Guardián de Entrada)
Herramienta | Descripción |
| Añadir aplicación a la lista de permitidos — el agente SOLO puede interactuar con aplicaciones listadas |
| Eliminar de la lista de permitidos |
| Restringir a una región de píxeles |
| Eliminar todas las restricciones |
| Estado del guardián, estadísticas de backend, información de alcance |
Pruebas en Segundo Plano
El Agente de Pantalla puede probar aplicaciones sin ocupar su pantalla. Tres modos, seleccionados automáticamente:
Modo 1: CDP (Chrome/Electron — cualquier Espacio, totalmente invisible)
# Start Chrome with debugging port
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222 --user-data-dir=/tmp/chrome-test# Connect — works even if Chrome is on a different desktop
window_scope(app="Chrome", url="localhost:3000")
# All operations go through Chrome's internal pipeline
interact(target="Submit", action="click")
interact(target="Email", action="click_and_type", text="test@example.com")
window_release()CDP evita el servidor de ventanas de macOS por completo. Las capturas de pantalla provienen del renderizador de Chrome, los clics pasan a través del sistema de entrada de Chrome. Su pantalla nunca es tocada.
Modo 2: Captura de Ventana (cualquier aplicación de macOS — mismo Espacio)
# Works with Figma, Xcode, Terminal, games — any app
window_scope(app="Figma", title="Design v2")
interact(target="Export", action="click")
window_release()Utiliza CGWindowListCreateImage para capturar la ventana incluso cuando está detrás de otras aplicaciones. Requiere el mismo Espacio de macOS.
Modo 3: Pantalla Completa (original)
Sin window_scope, opera en la pantalla completa como antes.
Prioridad de Respaldo
window_scope called → try CDP (Chrome) → try CGWindowList (same Space) → error
no scope → full screen modeGuardián de Entrada
El sistema de seguridad único del Agente de Pantalla con dos garantías:
Prioridad del Usuario — cualquier actividad de teclado/ratón pausa instantáneamente al agente. Se reanuda solo después de que usted haya estado inactivo durante 1.5s (configurable).
Bloqueo de Alcance — restringir al agente a aplicaciones específicas y/o regiones de pantalla.
# Agent can only interact with Chrome and Figma
add_app("Chrome")
add_app("Figma")
# Or restrict to a region
set_region(x=0, y=0, width=800, height=600)Configuración
Todos los parámetros son configurables a través de variables de entorno:
Variable | Predeterminado | Descripción |
| 1.5 | Segundos de enfriamiento del guardián |
| 0 | Establecer en "1" para deshabilitar |
| ax,cgevent,pyautogui | Orden de prioridad del backend |
| 2560 | Dimensión máxima de captura de pantalla |
| INFO | Nivel de registro |
Soporte de Plataforma
Característica | macOS | Windows | Linux |
Captura de pantalla | mss | mss | mss |
Entrada AX | Quartz AX | - | - |
Entrada CGEvent | Quartz | - | - |
Entrada pyautogui | respaldo | respaldo | respaldo |
Gestión de ventanas | AppleScript | - | wmctrl |
OCR | Vision Framework | - | - |
Escalado Retina | detección automática | - | - |
Captura de ventana | CGWindowListCreateImage | PrintWindow | xdotool+ImageMagick |
Desarrollo
git clone https://github.com/chriswu727/screen-agent
cd screen-agent
pip install -e ".[dev,macos]"
pytest tests/unit/ -v
ruff check src/ tests/Consulte DEVPATH.md para conocer el historial de desarrollo y las decisiones arquitectónicas.
Licencia
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Give your AI hands on every computer you own. Remote control of your Windows, Mac and Linux machines from one ChatGPT, Claude or Cursor chat — even from your phone. Ask it to find out why the office server is crawling, update every PC in the house, sort out your mom's laptop from another city, or ship the site from your work machine while you're on a train. It runs commands, reads files and takes a screenshot when it needs to see the screen. You decide what each computer allows, and you can cut any of them off in a second.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI to capture screenshots and control mouse and keyboard for automated desktop interaction.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to observe and control the user's live desktop by listing apps, reading accessibility trees, and performing clicks, typing, scrolling, dragging, and other input actions with per-action approvals and local audit archives.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to drive Windows desktop automation — opening and interacting with applications, native UI controls, keyboard/mouse input, files, processes, clipboard, and Chrome/Edge browsing via UI Automation and CDP. All actions pass through a safety policy with human approval, emergency stop, and deterministic verification.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to inspect and control allowlisted Windows applications using screenshots, mouse actions, Unicode keyboard input, UI Automation, and an Esc/F12 emergency stop.1Apache 2.0