gnome-screencast-mcp

Bildschirmaufnahme auf GNOME, gesteuert über die Befehlszeile oder einen KI-Agenten über MCP.

Nutzt den nativen Aufnahmemechanismus von GNOME Shell (das D-Bus-Interface org.gnome.Shell.Screencast, dasselbe, das auch hinter der Tastenkombination Strg+Alt+Umschalt+R steckt). Es hängt nicht von ffmpeg, wf-recorder oder irgendeinem anderen externen Capture-Binary ab.

Wofür ist das gut

Damit lassen sich Bildschirmaufnahmen automatisieren, ohne die grafische Oberfläche zu berühren: Demonstrationen, Bug-Nachweise, Dokumentation von Abläufen, Protokollierung von Test-Sitzungen. Da jeder Befehl JSON zurückgibt, eignet sich das Tool sowohl für Skripte als auch für einen Agenten, der aufzeichnen muss, was er gerade tut.

Das Problem, das es löst: GNOME D-Bus direkt aufzurufen, funktioniert zum Aufzeichnen nicht. Die Shell beendet die Aufnahme, sobald der D-Bus-Client, der sie gestartet hat, den Bus verlässt. Ein einzelner gdbus call erzeugt daher eine Datei mit genau einem Frame und einer Dauer von 0:00. Schließe sie bitte wieder ab – 0:00. Die Lösung hier ist ein Hilfsprozess, der die Verbindung über die gesamtes Aufnahme offen hält und sie beim Stop sauber beendet – nur so entsteht das WebM mit korrekter Dauer und korrektem Index.

Related MCP server: video-capture-mcp

Installation

Nichts klonen und nichts kompilieren. Vier Schritte: vom leeren System bis zum ersten aufgenommenen Video.

Noch nicht auf PyPI. Vorerst installiert uv direkt aus diesem GitHub-Repository – es funktioniert genauso, nur ist der Befehl ein wenig länger. Sobald das Paket auf PyPI ist, reicht gnome-screencast-mcp allein; die beiden Varianten sind dann austauschbar.

Schritt 1 — Anforderungen prüfen

Wenn alle drei Prüfungen fehlerfrei durchlaufen, fahre mit Schritt 2 fort.

Schritt 2 — installieren

uv tool install --from git+https://github.com/quinho981/gnome-screencast-mcp gnome-screencast-mcp

Das legt drei ausführbare Dateien in dein PATH:

Wenn das Terminal darauf hinweist, dass das installierte Verzeichnis nicht im PATH ist, führe den Befehl aus, den es vorschlägt (normalerweise uv tool update-shell) und öffne ein neues Terminal.

Schritt 3 — testen

gnome-screencast-start && sleep 3 && gnome-screencast-stop

Es sollte ein JSON mit "status": "recording" erscheinen, 3 Sekunden Pause, dann ein weiteres JSON mit "status": "stopped" und duration_seconds knapp über 3. Wenn das herauskommt, läuft alles – die .webm-Datei liegt in deinem Video-Verzeichnis.

Fehlgeschlagen? Dann gehe direkt weiter zu Problemen & Mängel.

Schritt 4 — Nutzungsart wählen

• Über die Befehlszeile: ist dann schon fertig – siehe Uses command command für gegebenfalls -o, -f, -a.

• Über einen KI-Agenten (Claude Code, Cursor, opencode usw.): Du musst den MCP-Server noch in deinem Client eintragen – siehe Uso via MCP, dort gibt es die Schritt für Schritt für jeden.

Ohne Install-Rennen: Du willst nur MCP in einem Agenten nutzen

Wenn du nur MCP nutzen willst, musst du nichts manuell installieren – der Client lädt das Paket beim Ausführen direkt herunter. Prüfe die Anforderungen aus Schritt 1, überspringe die Schritte 2 und 3 und gehe direkt zu Uso via MCP.

Eigene Entwicklung am Repository

Nur für die, die an diesem Repository Änderungen vornehmen:

git clone https://github.com/quinho981/gnome-screencast-mcp
cd gnome-screencast-mcp
uv run gnome-screencast-mcp        # servidor MCP a partir do código local
bash bin/start-recording.sh        # scripts de gravação, sem instalar nada
bash bin/stop-recording.sh

Struktur

Die Skripte liegen in bin/, damit sie direkt aus einem Klon benutzt werden können; der Wheel-Build kopiert sie in das Package und der Server findet sie an beiden Orten.

Verwendung über die Befehlszeile

# Tela inteira, 30 fps, arquivo com data e hora em ~/Vídeos
gnome-screencast-start

# ... faça o que precisa ser gravado ...

gnome-screencast-stop

In einem Klon sind die Entsprechungen bash bin/start-recording.sh und bash bin/stop-recording.sh.

Der Befehl start liefert den Dateipfad ab, sobald die Aufnahme beginnt:

{
  "status": "recording",
  "file": "/home/user/Vídeos/screencast-20260824-152940.webm",
  "mode": "screen",
  "framerate": 30,
  "draw_cursor": true,
  "started_at": "2026-08-24T15:29:40-0300",
  "pid": 183615
}

Und stop liefert die Zusammenfassung der Aufnahme:

{
  "status": "stopped",
  "file": "/home/user/Vídeos/screencast-20260824-152940.webm",
  "size_bytes": 361637,
  "duration_seconds": 4.488
}

Optionen für start

Beispiel — linke obere Ecke, 1280×720, 60 fps, ohne Cursor:

gnome-screencast-start -a 0 0 1280 720 -f 60 --no-cursor -o /tmp/demo.webm

Optionen für stop

Exit-Codes

Beide Befehle verwenden 0 für Erfolg und 1 für Nutzungs- oder Umgebungsfehler. Darüber hinaus:

• start: 2 es läuft bereits eine Aufnahme · 3 GNOME Shell hat den Start abgelehnt

• stop: 2 keine Aufnahme läuft · 3 Datei wurde nicht rechtzeitig finalisiert

Verwendung über MCP

Wenn du den Server registrierst، wird die Aufnahme zu einer Fähigkeit deines Agenten: Er ruft start_recording und stop_recording als typisierte Werkzeuge auf, ohne dass er Zugriff auf die Oberfläche braucht.

tools :

recording_status ist der schnelle Check-Vorgang, bevor man etwas tut – er verhindert, dass man eine bereits laufende Aufnahme startet oder eine nicht vorhandene stoppt.

Der Befehl – in jedem ähnnlichen Client

Der Server ist ein normaler stdio-Prozess, und der Befehl ist überall derselbe:

comando:    uvx
argumentos: gnome-screencast-mcp

Solange das Paket noch nicht auf PyPI ist, verwende in allen folgenden Beispielen diese Argumentliste statt ["gnome-screencast-mcp"]:

["--from", "git+https://github.com/quinho981/gnome-screencast-mcp", "gnome-screencast-mcp"]

Wenn das Paket veröffentlicht ist, wechsle zur kurzen Form zurück — die Beispiele sind bereits in ihr geschrieben.

Zwei Dinge können scheinbar funktionierende Konfigurationsdateien vergeigen:

1. uvx–Client liegt möglicherweise nicht im PATH.** Clients, die über einen grafischen Launcher gestartet werden (Cursor, VS Code, Zed. Claude Desktop), benutzen oft einen minimalen PATH ohne ~/.local/bin. Wenn der Server mit uvx: command not found fehlschlägt, ersetze uvx durch die Ausgabe von command -v uvx — normalerweise /home/<dein-system-benutzer>/.local/bin/uvx.

2. Die Aufnahme braucht den Sitzungs-Bus. Das D-Bus von GNOME wird über DBUS_SESSION_BUS_ADDRESS und XDG_RUNTIME_DIR verbunden. Ein Client, der aus deiner grafischen Sitzung heraus gestartet wurde, hat diese Variablen bereits. Ein Client in Container, Snap, Flatpak oder SSH-Sitzung hat das nicht — in diesem Fall deklariere beide im Block env des Servers:

   "env": {
     "DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/1000/bus",
     "XDG_RUNTIME_DIR": "/run/user/1000"
   }

   Die korrekten Werte für deinen Rechner erhältst du mit echo $DBUS_SESSION_BUS_ADDRESS $XDG_RUNTIME_DIR in einem Terminal der grafischen Sitzung.

Claude Code

Claude Code

claude mcp add screen-recorder --scope user \
  -- uvx --from git+https://github.com/quinho981/gnome-screencast-mcp gnome-screencast-mcp

Nach der Veröffentlichung auf PyPI wird es einfacher:-- uvx gnome-screencast-mcp.

Beginne das Sitzung neu und bestätige mit /mcp, dass screen-recorder als verbunden angezeigt wird.

Innerhalb dieses Repositories ist das nicht mal nötig: Das versionierte .mcp.json registriert den Server bereits im lokalen Code weiterverwendet – aproves einfach beim Öffnen des Verzeichnisses.

Codex CLI

codex mcp add screen-recorder \
  -- uvx --from git+https://github.com/quinho981/gnome-screencast-mcp gnome-screencast-mcp

Nach der Veröffentlichung auf PyPI wird es einfacher: -- uvx gnome-screencast-mcp.

Oder von Hand in ~/.codex/config.toml:

[mcp_servers.screen-recorder]
command = "uvx"
args = ["gnome-screencast-mcp"]

opencode

In opencode.json im Wurzelverzeichnis deines Projekts, oder in ~/.config/opencode/opencode.json, um für alle zu gelten:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "screen-recorder": {
      "type": "local",
      "enabled": true,
      "command": ["gnome-screencast-mcp"]
    }
  }
}

Das setzt das uv tool install aus Schritt 2 der Installation voraus; der Befehl ist nur der Name des ausführbaren Programms, bereits durch PATH aufgelöst. opencode markiert die Serverdatei als fehlgeschlagen (and resets enabled to false of itself), ist der Befehl nicht sofort ausführt. uvx gnome-screencast-mcp wird in diesem Fall unwahrscheinlich, solange das Package nicht auf PyPI st. Jeder Aufruf würde es von dort holen und scheitern. Wenn du das Installation nicht ausführen willst, Dann löse von die Write Storage the same without install across the clients [git+](#o-comando-em-qualquer-cliente):

"command": ["uvx", "--from", "git+https://github.com/quinho981/gnome-screencast-mcp", "gnome-screencast-mcp"]

opencode are the unique case where the command is a single list, not a separate command from the args.

Kürzer- Client

In ~/.cursor/mcp.json (global) oder .cursor/mcp.json (nur für dieses Projekt):

{
  "mcpServers": {
    "screen-recorder": {
      "command": "uvx",
      "args": ["gnome-screencast-mcp"]
    }
  }
}

Cursor error example: true

gnome

gemini mcp add screen-recorder \
  uvx --from git+https://github.com/quinho981/gnome-screencast-mcp gnome-screencast-mcp

Nach der Veröffentlichung auf PyPI wird es einfacher: uvx gnome-screencast-mcp.

Oder von Hand in ~/.gemini/settings.json (global) oder ..geming/settings.json(pro Projektdem), im gleichenmcpServers`-Format wie für Cursor oben abgebildet.

VS Code (GitHub Copilot)

In .vscode/mcp.json im Projekt. Beachte: Der Schlüssel servers wird servers genannt, nicht mcpServers, und der Typ wird explizit:

{
  "servers": {
    "screen-recorder": {
      "type": "stdio",
      "command": "uvx",
      "args": ["gnome-screencast-mcp"]
    }
  }
}

Windsurf

In ~/.codeium/windsurf/mcp_config.json, In the same mcpServers-Format as Cursor.

Zeichen

In der settings.json von Zed, unter context_servers:

{
  "context_servers": {
    "screen-recorder": {
      "source": "custom",
      "command": "uvx",
      "args": ["gnome-screencast-mcp"],
      "env": {}
    }
  }
}

Claude Desktop

Unter Linux in ~/.config/Claude/claude_desktop_config.json, im gleichen mcpServers-Format wie bei Cursor. Die App muss nach der Bearbeitung vollständig neu gestartet werden.

Andere Clients

Falls dein Client hier nicht aufgeführt ist, suche die Bildschirmfläche für „MCP servers“ in seiner Doku und setze den Befehl uvx mit der Option gnome-screencast-mcp ein.

Es gibt dabei im Wesentlich zwei Formate im gesamten Ökosystem: das Paar command + getrennte args (die Mehrheit) und das command als eine einzelne Liste (opencode).

Ohne uv

Das Paket ist ein normales Python-Projekt und pip kümmert sich darum:

pip install --user git+https://github.com/quinho981/gnome-screencast-mcp

(Nach der Veröffentlichung auf PyPI: pip install --user gnome-screencast-mcp.)

Der Client-Befehl lautet dann gnome-screencast-mcp, ohne Argumente. Auch eine eigene virtuelle Umgebung funktioniert – in diesem Fall zeigen Sie auf die ausführbare Datei in ihr; der Server entfernt sein eigenes venv aus dem PATH, den er an die Skripte weitergibt, damit diese das PyGObject des Systems weiterhin finden.

Server ohne Client testen

Bevor Sie sich mit der Konfiguration eines Agenten abmühen, sollten Sie prüfen, ob der Server hochkommt:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | uvx --from git+https://github.com/quinho981/gnome-screencast-mcp gnome-screencast-mcp

(Nach der Veröffentlichung auf PyPI genügt uvx gnome-screencast-mcp allein.)

Es sollte die Antwort des initialize erscheinen, gefolgt von den drei Tools. Beim ersten Aufruf gibt uvx außerdem eine Installationszeile auf stderr aus.

Funktionsweise

start-recording.sh
  └─ setsid recorder-daemon.py        (sobrevive ao script que o criou)
       ├─ D-Bus: Screencast(...)      → o GNOME Shell começa a gravar
       ├─ escreve o estado em $XDG_RUNTIME_DIR/screen-recorder/current.json
       └─ fica vivo, segurando a conexão, até receber SIGTERM

stop-recording.sh
  └─ SIGTERM no pid do estado
       └─ daemon: D-Bus StopScreencast pela mesma conexão
            └─ espera o GStreamer fechar o WebM e escreve o resumo final

Die Statusdatei stellt sicher, dass es jeweils nur eine Aufnahme gibt – eine Einschränkung der GNOME Shell selbst, die nur eine gleichzeitige Screencast-Sitzung unterstützt.

Wenn der Daemon stirbt, ohne aufgeräumt zu haben (z. B. bei einer Abmeldung), bleibt die Statusdatei verwaist: recording_status meldet stale, und der nächste start_recording entfernt sie von selbst.

Implementierungsdetails

Drei Fallstricke, die das Paket umgehen muss:

• Ausgabeerfassung. Der Server führt die Skripte mit umgeleiteter Ausgabe über temporäre Dateien aus, nicht über Pipes. Der Daemon erbt die Ausgabedeskriptoren, daher würde eine Pipe erst am Ende der Aufzeichnung ein EOF sehen – und der Aufruf von start_recording würde bis dahin hängen.

• Python-Umgebung. Nach der Installation läuft der Server in einer virtuellen Umgebung, die am Anfang des PATH steht. Die Skripte würden python3 dann dort auflösen, wo das PyGObject des Systems nicht vorhanden ist. Der Server entfernt das venv aus der Umgebung, die die Skripte erben.

• Ausführungsbit. Die Skripte werden als bash script.sh und der Daemon als python3 daemon.py aufgerufen, nie direkt: Die Ausführungsberechtigung übersteht das Verpacken als Wheel nicht zuverlässig.

Häufige Probleme

PyGObject não encontrado – installieren Sie es mit sudo apt install python3-gi. Wenn the Message nur bei der Verwendung von MCP erscheint und nicht in der Befehlszeile, wird das venv in den PATH der Skripte weitergereicht.

Der Agent listet die Tools nicht – der Server wurde gar nicht erst gestartet. Führen Sie den Test unter Server ohne Client testen aus; wenn er besteht, liegt das Problem in der Client-Konfiguration, fast immer daran, dass uvx nicht im PATH liegt (Punkt 1 von Der Befehl in beliebigem Client).

o GNOME Shell recusou iniciar a gravação – normalerweise gibt es keine zugreifbare GNOME-Sitzung. Der MCP-Server erbt die Umgebung dessen, der ihn gestartet hat, und D-Bus braucht DBUS_SESSION_BUS_ADDRESS und XDG_RUNTIME_DIR. Läuft der MCP-Client in einer abgeschotteten Umgebung (Container, Snap, Flatpak, Dienst, SSH), deklarieren Sie die beiden Variablen im env-Block des Servers – siehe Punkt 2 von Der Befehl bei jedem Client.

gravação já em andamento – rufen Sie stop_recording oder gnome-screencast-stop auf. Zum manuellen Prüfen des Zustands: cat $XDG_RUNTIME_DIR/screen-recorder/current.json.

Video mit Dauer 0:00 – ein Zeichen, dass die Aufnahme außerhalb dieser Befehle gestartet wurde, mit einem D-Bus-Client, der nicht überlebt hat. Verwenden Sie gnome-screencast-start.

Log des Hilfsprozesses: $XDG_RUNTIME_DIR/screen-recorder/daemon.log.

Lizenz

MIT – siehe LICENSE.

Eine Version veröffentlichen

uv build          # gera dist/*.whl e dist/*.tar.gz
uv publish        # envia ao PyPI

Die Version steht in pyproject.toml.