Skip to main content
Glama

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 — act liefert einen Screenshot zur visuellen Analyse durch das LLM und führt dann Aktionen an den vom LLM bereitgestellten Koordinaten aus. eval_js fü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

AXPerformAction

Native macOS-Apps — semantisch, keine Koordinaten erforderlich

2

CGEvent

CGEventPost

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 serve

Mit 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 check

Tools

Wahrnehmung

Tool

Beschreibung

capture_screen

Screenshot (vollständig oder Bereich), liefert Bild für visuelle Analyse

list_windows

Alle sichtbaren Fenster mit Positionen auflisten

get_active_window

Aktuell fokussiertes Fenster

get_cursor_position

Aktuelle Mausposition

Eingabe (alle unterstützen verify: true für Screenshots nach der Aktion)

Tool

Beschreibung

click

An Koordinaten klicken (links/rechts/mitte, Mehrfachklick)

type_text

Text am Cursor eingeben (Unicode via Zwischenablage auf macOS)

press_key

Tastendruck mit Modifikatoren (z. B. Cmd+C)

scroll

Scrollrad an optionaler Position

move_mouse

Cursor bewegen, ohne zu klicken

drag

Klicken und Ziehen zwischen zwei Punkten

focus_window

Fenster durch teilweisen Titelabgleich in den Vordergrund bringen

OCR (erkennt automatisch Chinesisch, Japanisch, Koreanisch, Englisch)

Tool

Beschreibung

ocr

Gesamten Text mit Begrenzungsrahmen extrahieren

find_text

Text finden und Position zurückgeben

click_text

Text finden und auf dessen Mitte klicken

Autonomes Testen (das Alleinstellungsmerkmal)

Tool

Beschreibung

run_test

Einen vollständigen Testplan autonom ausführen — keine LLM-Roundtrips. 15x schneller.

act

Vision-First: liefert Screenshot → LLM schaut → führt an Koordinaten aus

eval_js

JavaScript über CDP ausführen. DOM-Assertionen, Elementklicks, Zustandsprüfungen

interact

OCR-basiert: Element anhand von Text finden + klicken/eingeben in einem Aufruf

Hintergrundtests

Tool

Beschreibung

window_scope

Auf ein Fenster sperren. Chrome: Auto-CDP (beliebiger Space). Native: CGWindowList (gleicher Space).

window_release

Fenster-Scope freigeben, zum Vollbildmodus zurückkehren

Visuelle E2E-Tests

Tool

Beschreibung

test_start

Testsitzung mit automatischer Screenshot-Sammlung starten

test_step

Testschritt beginnen (erfasst automatisch "Vorher"-Screenshot)

test_verify

Schritt über OCR-Textprüfung oder Screenshot-Diff verifizieren

test_end

Sitzung beenden, Markdown-Bericht mit Nachweisen erstellen

test_status

Aktueller Sitzungsstatus

Sicherheit (Input Guardian)

Tool

Beschreibung

add_app

App zur Allowlist hinzufügen — Agent kann NUR mit gelisteten Apps interagieren

remove_app

Von Allowlist entfernen

set_region

Auf Pixelbereich beschränken

clear_scope

Alle Einschränkungen entfernen

get_agent_status

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 mode

Input Guardian

Das einzigartige Sicherheitssystem von Screen Agent mit zwei Garantien:

  1. Benutzerpriorität — jede Tastatur-/Mausaktivität pausiert den Agenten sofort. Er setzt die Arbeit erst fort, nachdem Sie 1,5s (konfigurierbar) inaktiv waren.

  2. 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

SCREEN_AGENT_COOLDOWN

1.5

Guardian-Abklingzeit in Sekunden

SCREEN_AGENT_GUARDIAN_DISABLED

0

Auf "1" setzen, um zu deaktivieren

SCREEN_AGENT_INPUT_BACKENDS

ax,cgevent,pyautogui

Prioritätsreihenfolge der Backends

SCREEN_AGENT_MAX_DIMENSION

2560

Maximale Screenshot-Dimension

SCREEN_AGENT_LOG_LEVEL

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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI clients to inspect and control allowlisted Windows applications using screenshots, mouse actions, Unicode keyboard input, UI Automation, and an Esc/F12 emergency stop.
      1
      Apache 2.0