Back to search
screen-record-mcp
SkillWorks with Claude CodeGitHub
MCP server for screen+audio recording on KDE Plasma/Wayland (xdg-desktop-portal + GStreamer)
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/strubedo--screen-record-mcp)HTML
<a href="/listings/strubedo--screen-record-mcp"><img src="/api/listings/strubedo--screen-record-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
python3 -m venv .venv .venv/bin/pip install -e .
Register it with a Claude Code (or any MCP-compatible) client:
claude mcp add screen-record -- /path/to/.venv/bin/python -m mcp_screen_record.server
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 49 lines
- # screen-record — SKILL.md
- ## Overview
- Screen and audio recording on KDE Plasma/Wayland. Wraps the xdg-desktop-portal ScreenCast permission flow and a GStreamer (pipewiresrc + x264enc + voaacenc + mp4mux) encoding pipeline, with a supervisor process that keeps the recorder's real parent alive so the output file finalizes correctly (has a moov atom) when stopped.
- ## Tools
- ### `start_recording`
- Start a screen recording (with system audio by default, or video-only) to a given output .mp4 path.
- **Parameters:** (none)
- ### `stop_recording`
- Stop the current recording so the output file is properly finalized and playable.
- **Parameters:** (none)
- ### `check_recording_status`
- Check whether a recording is currently in progress, and if so, its output path.
- **Parameters:** (none)
- ## Usage Patterns
- This server exposes the following access patterns:
- - Start a screen recording (with system audio by default, or video-only) to a given output .mp4 path.
- - Stop the current recording so the output file is properly finalized and playable.
- - Check whether a recording is currently in progress, and if so, its output path.
- ## Gotchas
- - Always check the response for error fields before proceeding.
- - Pass `verbose=true` on any tool to get the full response payload; the compact default may omit fields you need.
- ## Recipe Workflows
- ### uc-01: Start a screen recording (with system audio by default, or video-only) to a given output .mp4 path.
- 1. Call `start_recording` — Start a screen recording (with system audio by default, or video-only) to a given output .mp4 path.
- 2. Call `check_recording_status` — Check whether a recording is currently in progress, and if so, its output path.
- ### uc-02: Stop the current recording so the output file is properly finalized and playable.
- 1. Call `stop_recording` — Stop the current recording so the output file is properly finalized and playable.
- 2. Call `check_recording_status` — Check whether a recording is currently in progress, and if so, its output path.
- ### uc-03: Check whether a recording is currently in progress, and if so, its output path.
- 1. Call `check_recording_status` — Check whether a recording is currently in progress, and if so, its output path.
- 2. Call `start_recording` — Start a screen recording (with system audio by default, or video-only) to a given output .mp4 path.
- ## Composed-Call Examples
- (No composed tools defined)
- ## Anti-patterns
- - Do not ignore the `verbose` parameter when you need metadata for debugging.
- - Do not assume tools are idempotent unless their description says so.
README.md · README · 67 lines
- # screen-record-mcp
- An MCP server that records screen + system audio on KDE Plasma/Wayland, so an
- LLM agent can start, stop, and check on recordings.
- It wraps two things:
- - **`xdg-desktop-portal`'s `ScreenCast` D-Bus interface** for the permission
- flow (the real, user-facing "Share screen with..." dialog), with
- `persist_mode` so you only approve it once per app.
- - **GStreamer** (`pipewiresrc` + `x264enc` + `voaacenc` + `mp4mux`) for
- encoding to a standard `.mp4`.
- A small supervisor process keeps the GStreamer pipeline's real OS-level
- parent alive so that stopping a recording finalizes the output file properly
- (writes the `moov` atom) instead of leaving a corrupt `.mp4`.
- ## Requirements
- - KDE Plasma 6 on Wayland (uses `org.freedesktop.portal.ScreenCast`)
- - `gstreamer1.0-tools` and the usual good/bad/ugly plugin sets (for
- `pipewiresrc`, `x264enc`, `voaacenc`)
- - PyGObject (`python3-gi`) — needed for real D-Bus fd-passing, which the
- `gdbus` CLI can't do
- - Python >= 3.10
- ## Install
- ```bash
- python3 -m venv .venv
- .venv/bin/pip install -e .
- ```
- Register it with a Claude Code (or any MCP-compatible) client:
- ```bash
- claude mcp add screen-record -- /path/to/.venv/bin/python -m mcp_screen_record.server
- ```
- ## Tools
- | Tool | Description |
- |---|---|
- | `start_recording` | Start a screen recording (with system audio by default, or video-only) to a given output path. |
- | `stop_recording` | Stop the current recording so the output file is properly finalized and playable. |
- | `check_recording_status` | Check whether a recording is in progress, and its output path. |
- ## How it works
- 1. `start_recording` drives the portal handshake: `CreateSession` →
- `SelectSources` → `Start` → `OpenPipeWireRemote`, which hands back a
- PipeWire node ID and a Unix file descriptor for the video stream.
- 2. It double-forks a supervisor process that launches `gst-launch-1.0` as its
- real child, then blocks on `os.waitpid()`.
- 3. `stop_recording` sends `SIGTERM` to the supervisor, which relays `SIGINT`
- to `gst-launch-1.0` — the `-e` flag makes that trigger a clean
- EOS-and-finalize instead of a hard kill.
- The double-fork matters: a recorder process that gets reparented to init
- (e.g. if its original launching process exits) can silently stop responding
- correctly to a graceful-shutdown signal, corrupting the output file. The
- supervisor is `gst-launch-1.0`'s real parent for the life of the recording,
- so that failure mode doesn't happen.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.