screen-mcp

Ein MCP-Server (Model Context Protocol), der KI-Agenten Augen auf einem Omarchy / Hyprland-Wayland-Desktop verleiht. Er erfasst Screenshots über grim und bietet eine optionale Bildanalyse mithilfe der Gemini API an — nützlich, wenn das aufrufende Modell keinen nativen Vision-Encoder besitzt.

Funktionen

Screenshots verwenden grim (wlroots-Screencopy-Protokoll) — kein X11 erforderlich.

Voraussetzungen

• Omarchy, Hyprland oder einen beliebigen wlroots-basierten Wayland-Compositor

• grim — Wayland-Screenshot-Tool

• slurp — (optional) Hilfsprogramm für die interaktive Bereichsauswahl

• hyprctl — Hyprland-Fenster-/Abfrage-CLI

• jq — (optional) wird von einigen Hilfsskripten verwendet

Überprüfen mit:

grim --help && hyprctl clients -j | head -c 20

Für die Bildanalyse (optional)

• Einen Gemini-API-Schlüssel erhältst du unter https://aistudio.google.com

• Exportiere ihn in deiner Umgebung:

export GEMINI_API_KEY="your-api-key-here"

Ohne den Schlüssel funktionieren die Screenshot-Tools weiterhin; nur analyze_image und screenshot_and_analyze geben einen Fehler zurück.

Installation

Über Claude Desktop

Füge Folgendes zur claude_desktop_config.json deiner Claude-Desktop-Installation hinzu:

{
  "mcpServers": {
    "screen-mcp": {
      "command": "npx",
      "args": ["-y", "screen-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Über npx

npx -y screen-mcp

# Or install globally:
npm install -g screen-mcp

Verwendungsbeispiele

Einen Bildschirmbereich erfassen

screenshot_region(x=100, y=200, width=800, height=600, include_cursor=true)

Ein bestimmtes Fenster erfassen

Liste zuerst die verfügbaren Fenster auf, um eine Adresse oder einen Titel zu erhalten:

list_windows()

Erfasse das Fenster dann über Titel (Teilstring-Übereinstimmung), Adresse oder "focused":

screenshot_window(window="Spotify")
screenshot_window(window="focused")
screenshot_window(window="0x557ba79b4900")

Ein Bild mit Gemini analysieren

analyze_image(
  image_path="/tmp/my-screenshot.png",
  prompt="What applications are visible in this screenshot?",
  model="gemini-2.5-flash"
)

Oder gib base64-codierte Bilddaten direkt weiter:

analyze_image(
  image="<base64-encoded-image>",
  prompt="Describe what you see in this image.",
  mime_type="image/png"
)

Erfassen und Analysieren in einem Aufruf

screenshot_and_analyze(
  x=0, y=0, width=1920, height=1080,
  prompt="Count the number of windows open and list their titles.",
  scale=0.5,
  model="gemini-2.5-flash"
)

Entwicklung

# Install deps
npm install

# Build
npm run build

# Run
npm start

# Development (recompile on change)
npm run dev

So funktioniert es

• Erfassung: src/capture.ts kapselt grim (Screenshots) und hyprctl (Fensterauflistung). Für die Fenster-Erfassung wird zuerst grim -T <stableId> (Foreign-Toplevel-Handle) versucht; alternativ wird auf grim -g "<x>,<y> <w>x<h>" (Geometrie von hyprctl) zurückgegriffen.

• Analyse: src/gemini.ts verwendet das offizielle @google/genai-SDK. Bilder werden inline als base64 an den interactions.create-Endpunkt der Gemini-API übergeben.

• Server: src/index.ts verbindet alles zu einem über stdio transportierten MCP-Server mithilfe von @modelcontextprotocol/server.

Lizenz

MIT