Screen Agent
Screen Agent
KI-nativer Test-Agent, der Ihre App wie ein echter Benutzer sieht — 15x schneller als Claude Code, ohne Ihren Bildschirm zu berühren.
Ein MCP-Server für autonomes visuelles Testen. Die KI plant Testschritte in natürlicher Sprache, der Server führt sie alle ohne LLM-Roundtrips aus. Funktioniert im Hintergrund über CDP (Chrome) oder Accessibility API (native Apps).
Kurze Demo
# 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
Warum?
Jedes Test-Tool zwingt Sie zur Wahl: schnell, aber fehleranfällig (Playwright) oder intelligent, aber langsam (Claude Code Computer Use). Screen Agent ist beides:
Autonome Ausführung —
run_test()führt ALLE Schritte serverseitig aus. Keine LLM-Roundtrips. 150ms/Schritt gegenüber 1-3s/Schritt bei Claude Code. 15x schneller.Vision-First — das LLM SIEHT den Bildschirm und entscheidet, wo geklickt werden soll. Keine DOM-Selektoren. UI-Änderungen lassen Tests nicht fehlschlagen, da das LLM den Bildschirm neu interpretiert.
act+eval_js—actliefert einen Screenshot zur visuellen Analyse durch das LLM und führt dann Aktionen an den vom LLM bereitgestellten Koordinaten aus.eval_jsführt JavaScript über CDP für Assertionen aus. 5 Tests in 0,6s.Hintergrundtests —
window_scope+ CDP ermöglicht es Ihnen, Chrome-Apps auf jedem macOS-Space zu testen, ohne den Bildschirm des Benutzers zu berühren. Bei nativen Apps werden Tests hinter anderen Fenstern auf demselben Space ausgeführt.Multi-Backend-Eingabekette — drei Eingabemethoden (Accessibility API → CGEvent → pyautogui) mit automatischem Fallback. Funktioniert mit nativen Apps, Electron-Apps und Game-Engines.
Input Guardian — Echtzeit-Sicherheitssystem, das alle Agenten-Aktionen pausiert, sobald Sie Ihre Maus oder Tastatur berühren. Kein anderes Tool bietet dies.
App-übergreifende Workflows — Testabläufe, die mehrere Apps umspannen (E-Mail → Browser → Slack). Kein anderes Tool kann dies, da sie alle auf einzelne Apps beschränkt sind.
Architektur
┌──────────────────────────────────┐
│ 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
└──────────────────────────────────┘Eingabe-Backend-Kette
Die zentrale Design-Herausforderung: pyautogui funktioniert für ca. 80 % der Apps, versagt aber bei Game-Engines und vielen Electron-Apps. Screen Agent löst dies mit einem Chain of Responsibility-Muster:
Priorität | Backend | Methode | Am besten geeignet für |
1 | AX |
| Native macOS-Apps — semantisch, keine Koordinaten erforderlich |
2 | CGEvent |
| Spiele, Electron — native OS-Event-Injektion |
3 | pyautogui | Python-Wrapper | Plattformübergreifendes Fallback |
Jedes Backend implementiert dasselbe InputBackend-Protokoll. Wenn eines fehlschlägt, versucht die Kette automatisch das nächste. Alle Versuche werden zur Beobachtbarkeit mit Telemetrie protokolliert.
Installation
pip install screen-agent
# Recommended: install macOS native backends
pip install screen-agent[macos]Schnellstart
Mit Claude Code
claude mcp add screen -- screen-agent serveMit Cursor / anderen MCP-Clients
Fügen Sie dies zu Ihrer MCP-Konfiguration hinzu:
{
"mcpServers": {
"screen": {
"command": "screen-agent",
"args": ["serve"]
}
}
}Systemfähigkeiten prüfen
screen-agent checkTools
Wahrnehmung
Tool | Beschreibung |
| Screenshot (vollständig oder Bereich), liefert Bild für visuelle Analyse |
| Alle sichtbaren Fenster mit Positionen auflisten |
| Aktuell fokussiertes Fenster |
| Aktuelle Mausposition |
Eingabe (alle unterstützen verify: true für Screenshots nach der Aktion)
Tool | Beschreibung |
| An Koordinaten klicken (links/rechts/mitte, Mehrfachklick) |
| Text am Cursor eingeben (Unicode via Zwischenablage auf macOS) |
| Tastendruck mit Modifikatoren (z. B. Cmd+C) |
| Scrollrad an optionaler Position |
| Cursor bewegen, ohne zu klicken |
| Klicken und Ziehen zwischen zwei Punkten |
| Fenster durch teilweisen Titelabgleich in den Vordergrund bringen |
OCR (erkennt automatisch Chinesisch, Japanisch, Koreanisch, Englisch)
Tool | Beschreibung |
| Gesamten Text mit Begrenzungsrahmen extrahieren |
| Text finden und Position zurückgeben |
| Text finden und auf dessen Mitte klicken |
Autonomes Testen (das Alleinstellungsmerkmal)
Tool | Beschreibung |
| Einen vollständigen Testplan autonom ausführen — keine LLM-Roundtrips. 15x schneller. |
| Vision-First: liefert Screenshot → LLM schaut → führt an Koordinaten aus |
| JavaScript über CDP ausführen. DOM-Assertionen, Elementklicks, Zustandsprüfungen |
| OCR-basiert: Element anhand von Text finden + klicken/eingeben in einem Aufruf |
Hintergrundtests
Tool | Beschreibung |
| Auf ein Fenster sperren. Chrome: Auto-CDP (beliebiger Space). Native: CGWindowList (gleicher Space). |
| Fenster-Scope freigeben, zum Vollbildmodus zurückkehren |
Visuelle E2E-Tests
Tool | Beschreibung |
| Testsitzung mit automatischer Screenshot-Sammlung starten |
| Testschritt beginnen (erfasst automatisch "Vorher"-Screenshot) |
| Schritt über OCR-Textprüfung oder Screenshot-Diff verifizieren |
| Sitzung beenden, Markdown-Bericht mit Nachweisen erstellen |
| Aktueller Sitzungsstatus |
Sicherheit (Input Guardian)
Tool | Beschreibung |
| App zur Allowlist hinzufügen — Agent kann NUR mit gelisteten Apps interagieren |
| Von Allowlist entfernen |
| Auf Pixelbereich beschränken |
| Alle Einschränkungen entfernen |
| Guardian-Status, Backend-Statistiken, Scope-Informationen |
Hintergrundtests
Screen Agent kann Anwendungen testen, ohne Ihren Bildschirm zu belegen. Drei Modi, automatisch ausgewählt:
Modus 1: CDP (Chrome/Electron — beliebiger Space, völlig unsichtbar)
# 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 umgeht den macOS-Window-Server vollständig. Screenshots stammen vom Chrome-Renderer, Klicks gehen durch das Eingabesystem von Chrome. Ihr Bildschirm wird nie berührt.
Modus 2: Fenstererfassung (jede macOS-App — gleicher Space)
# Works with Figma, Xcode, Terminal, games — any app
window_scope(app="Figma", title="Design v2")
interact(target="Export", action="click")
window_release()Verwendet CGWindowListCreateImage, um das Fenster zu erfassen, selbst wenn es hinter anderen Apps liegt. Erfordert denselben macOS-Space.
Modus 3: Vollbild (ursprünglich)
Ohne window_scope arbeitet es wie bisher auf dem gesamten Bildschirm.
Fallback-Priorität
window_scope called → try CDP (Chrome) → try CGWindowList (same Space) → error
no scope → full screen modeInput Guardian
Das einzigartige Sicherheitssystem von Screen Agent mit zwei Garantien:
Benutzerpriorität — jede Tastatur-/Mausaktivität pausiert den Agenten sofort. Er setzt die Arbeit erst fort, nachdem Sie 1,5s (konfigurierbar) inaktiv waren.
Scope-Sperre — beschränken Sie den Agenten auf bestimmte Apps und/oder Bildschirmbereiche.
# 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)Konfiguration
Alle Parameter sind über Umgebungsvariablen konfigurierbar:
Variable | Standard | Beschreibung |
| 1.5 | Guardian-Abklingzeit in Sekunden |
| 0 | Auf "1" setzen, um zu deaktivieren |
| ax,cgevent,pyautogui | Prioritätsreihenfolge der Backends |
| 2560 | Maximale Screenshot-Dimension |
| INFO | Protokollierungsebene |
Plattformunterstützung
Funktion | macOS | Windows | Linux |
Screenshot | mss | mss | mss |
AX-Eingabe | Quartz AX | - | - |
CGEvent-Eingabe | Quartz | - | - |
pyautogui-Eingabe | Fallback | Fallback | Fallback |
Fensterverwaltung | AppleScript | - | wmctrl |
OCR | Vision Framework | - | - |
Retina-Skalierung | Auto-Erkennung | - | - |
Fenstererfassung | CGWindowListCreateImage | PrintWindow | xdotool+ImageMagick |
Entwicklung
git clone https://github.com/chriswu727/screen-agent
cd screen-agent
pip install -e ".[dev,macos]"
pytest tests/unit/ -v
ruff check src/ tests/Siehe DEVPATH.md für Entwicklungsgeschichte und architektonische Entscheidungen.
Lizenz
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