Skip to main content
Glama
screen-record-mcp

screen-record-mcp

by strubedo

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

Related MCP server: gnome-screencast-mcp

Install

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

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

Available Tools

3 tools
check_recording_statusCheck Recording StatusA

Check whether a recording is currently in progress, and if so, its output path.

Inputs: no named parameters.

start_recordingStart RecordingB

Start a screen recording (with system audio by default, or video-only) to a given output .mp4 path. The first call on a fresh system may require the user to approve a one-time KDE screen-share permission dialog on their desktop - this cannot be approved programmatically.

Inputs: audio, output.

stop_recordingStop RecordingA

Stop the current recording so the output file is properly finalized and playable. No-op (returns stopped=False) if no recording is in progress.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to create and manage macOS screen recordings through a semantic demo plan, including permission checks, source listing, and durable recording jobs.
      4 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables an LLM agent to control a local OBS Studio instance via obs-websocket, launching it, arranging scenes and sources, and starting or stopping recordings so it can capture its own screen as raw footage without manual intervention.
      1
      MIT