Skip to content
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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/strubedo--screen-record-mcp/badge.svg)](/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
  1. # screen-record — SKILL.md
  2. ## Overview
  3. 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.
  4. ## Tools
  5. ### `start_recording`
  6. Start a screen recording (with system audio by default, or video-only) to a given output .mp4 path.
  7. **Parameters:** (none)
  8. ### `stop_recording`
  9. Stop the current recording so the output file is properly finalized and playable.
  10. **Parameters:** (none)
  11. ### `check_recording_status`
  12. Check whether a recording is currently in progress, and if so, its output path.
  13. **Parameters:** (none)
  14. ## Usage Patterns
  15. This server exposes the following access patterns:
  16. - Start a screen recording (with system audio by default, or video-only) to a given output .mp4 path.
  17. - Stop the current recording so the output file is properly finalized and playable.
  18. - Check whether a recording is currently in progress, and if so, its output path.
  19. ## Gotchas
  20. - Always check the response for error fields before proceeding.
  21. - Pass `verbose=true` on any tool to get the full response payload; the compact default may omit fields you need.
  22. ## Recipe Workflows
  23. ### uc-01: Start a screen recording (with system audio by default, or video-only) to a given output .mp4 path.
  24. 1. Call `start_recording` — Start a screen recording (with system audio by default, or video-only) to a given output .mp4 path.
  25. 2. Call `check_recording_status` — Check whether a recording is currently in progress, and if so, its output path.
  26. ### uc-02: Stop the current recording so the output file is properly finalized and playable.
  27. 1. Call `stop_recording` — Stop the current recording so the output file is properly finalized and playable.
  28. 2. Call `check_recording_status` — Check whether a recording is currently in progress, and if so, its output path.
  29. ### uc-03: Check whether a recording is currently in progress, and if so, its output path.
  30. 1. Call `check_recording_status` — Check whether a recording is currently in progress, and if so, its output path.
  31. 2. Call `start_recording` — Start a screen recording (with system audio by default, or video-only) to a given output .mp4 path.
  32. ## Composed-Call Examples
  33. (No composed tools defined)
  34. ## Anti-patterns
  35. - Do not ignore the `verbose` parameter when you need metadata for debugging.
  36. - Do not assume tools are idempotent unless their description says so.
README.md · README · 67 lines
  1. # screen-record-mcp
  2. An MCP server that records screen + system audio on KDE Plasma/Wayland, so an
  3. LLM agent can start, stop, and check on recordings.
  4. It wraps two things:
  5. - **`xdg-desktop-portal`'s `ScreenCast` D-Bus interface** for the permission
  6. flow (the real, user-facing "Share screen with..." dialog), with
  7. `persist_mode` so you only approve it once per app.
  8. - **GStreamer** (`pipewiresrc` + `x264enc` + `voaacenc` + `mp4mux`) for
  9. encoding to a standard `.mp4`.
  10. A small supervisor process keeps the GStreamer pipeline's real OS-level
  11. parent alive so that stopping a recording finalizes the output file properly
  12. (writes the `moov` atom) instead of leaving a corrupt `.mp4`.
  13. ## Requirements
  14. - KDE Plasma 6 on Wayland (uses `org.freedesktop.portal.ScreenCast`)
  15. - `gstreamer1.0-tools` and the usual good/bad/ugly plugin sets (for
  16. `pipewiresrc`, `x264enc`, `voaacenc`)
  17. - PyGObject (`python3-gi`) — needed for real D-Bus fd-passing, which the
  18. `gdbus` CLI can't do
  19. - Python >= 3.10
  20. ## Install
  21. ```bash
  22. python3 -m venv .venv
  23. .venv/bin/pip install -e .
  24. ```
  25. Register it with a Claude Code (or any MCP-compatible) client:
  26. ```bash
  27. claude mcp add screen-record -- /path/to/.venv/bin/python -m mcp_screen_record.server
  28. ```
  29. ## Tools
  30. | Tool | Description |
  31. |---|---|
  32. | `start_recording` | Start a screen recording (with system audio by default, or video-only) to a given output path. |
  33. | `stop_recording` | Stop the current recording so the output file is properly finalized and playable. |
  34. | `check_recording_status` | Check whether a recording is in progress, and its output path. |
  35. ## How it works
  36. 1. `start_recording` drives the portal handshake: `CreateSession` →
  37. `SelectSources` → `Start` → `OpenPipeWireRemote`, which hands back a
  38. PipeWire node ID and a Unix file descriptor for the video stream.
  39. 2. It double-forks a supervisor process that launches `gst-launch-1.0` as its
  40. real child, then blocks on `os.waitpid()`.
  41. 3. `stop_recording` sends `SIGTERM` to the supervisor, which relays `SIGINT`
  42. to `gst-launch-1.0` — the `-e` flag makes that trigger a clean
  43. EOS-and-finalize instead of a hard kill.
  44. The double-fork matters: a recorder process that gets reparented to init
  45. (e.g. if its original launching process exits) can silently stop responding
  46. correctly to a graceful-shutdown signal, corrupting the output file. The
  47. supervisor is `gst-launch-1.0`'s real parent for the life of the recording,
  48. so that failure mode doesn't happen.
  49. ## License
  50. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.