Skip to main content
Glama
screen-record-mcp

screen-record-mcp

by strubedo
README.md
# 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

TDQS

A4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool maps to a distinct phase of the recording lifecycle: start begins capture, stop finalizes the file, and check_recording_status is a read-only query. There is no plausible confusion between starting, stopping, and inspecting a recording.

Naming Consistency5/5

All three tools use snake_case with a verb_noun pattern (start_recording, stop_recording, check_recording_status). The convention is uniform and immediately readable.

Tool Count5/5

Three tools exactly cover the lifecycle of a single-domain screen recorder, and each one earns its place with no filler. The surface is lean but appropriately scoped for a narrowly focused server.

Completeness4/5

Start, stop, and status form a complete lifecycle with no dead ends, and status even exposes the output path. Minor gaps exist: no pause/resume and no way to enumerate or manage prior recordings, though these are easily worked around.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues