screen-record-mcp
Provides screen and system-audio recording on KDE Plasma 6 Wayland through the xdg-desktop-portal ScreenCast permission flow, with tools to start, stop, and check recordings saved as MP4 files.
Enables screen and system-audio capture in a Wayland/KDE Plasma environment via the xdg-desktop-portal ScreenCast interface, exposing start, stop, and status tools for recordings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@screen-record-mcp record my screen with system audio to ~/Videos/demo.mp4"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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'sScreenCastD-Bus interface for the permission flow (the real, user-facing "Share screen with..." dialog), withpersist_modeso 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-toolsand the usual good/bad/ugly plugin sets (forpipewiresrc,x264enc,voaacenc)PyGObject (
python3-gi) — needed for real D-Bus fd-passing, which thegdbusCLI can't doPython >= 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.serverTools
Tool | Description |
| Start a screen recording (with system audio by default, or video-only) to a given output path. |
| Stop the current recording so the output file is properly finalized and playable. |
| Check whether a recording is in progress, and its output path. |
How it works
start_recordingdrives the portal handshake:CreateSession→SelectSources→Start→OpenPipeWireRemote, which hands back a PipeWire node ID and a Unix file descriptor for the video stream.It double-forks a supervisor process that launches
gst-launch-1.0as its real child, then blocks onos.waitpid().stop_recordingsendsSIGTERMto the supervisor, which relaysSIGINTtogst-launch-1.0— the-eflag 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 toolscheck_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
Scored across 3 tools
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.
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.
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.
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
Related MCP Connectors
Screen recording, meeting notes, and voice dictation - all with AI
Transform video, audio and images, and generate media from prompts. FFmpeg, captions, models.
FFmpeg as a service for AI agents: typed video editing tools, async jobs, downloadable outputs.
Productivity toolbox for Personal Agents: create PPTs, covers, websites, music and process files.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to start and stop full-screen recordings on macOS using FFmpeg, with control over quality, FPS, and audio.5MIT
- AlicenseAqualityDmaintenanceEnables AI agents to start and stop native GNOME Shell screen recordings via MCP tools, returning JSON with file path, size, and duration without depending on ffmpeg or wf-recorder.3MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to create and manage macOS screen recordings through a semantic demo plan, including permission checks, source listing, and durable recording jobs.4 npmApache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables 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.1MIT