Screencast MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| FFMPEG_PATH | No | Path to the ffmpeg executable. ffmpeg and ffprobe are external dependencies and must be on PATH, or pointed at via the FFMPEG_PATH / FFPROBE_PATH environment variables. The server detects them per call and returns a clear error with an install hint if either is missing. | |
| FFPROBE_PATH | No | Path to the ffprobe executable. ffmpeg and ffprobe are external dependencies and must be on PATH, or pointed at via the FFMPEG_PATH / FFPROBE_PATH environment variables. The server detects them per call and returns a clear error with an install hint if either is missing. | |
| SCREENCAST_HOME | No | Output is written under SCREENCAST_HOME (default <homedir>/.screencast-mcp) into recordings/, frames/, screenshots/, and edits/. | <homedir>/.screencast-mcp |
| SCREENCAST_WHISPER_MODEL | No | Speech to an SRT file, locally, with FFmpeg 8's whisper filter (needs a whisper.cpp model: pass model or set SCREENCAST_WHISPER_MODEL). | |
| SCREENCAST_JOB_TIMEOUT_MS | No | The job timeout scales with the media's length (at least 10 minutes, or 4x the duration); set SCREENCAST_JOB_TIMEOUT_MS to override it. | |
| SCREENCAST_MAX_RECORDING_SEC | No | Set SCREENCAST_MAX_RECORDING_SEC to change the default recording cap (0 disables it). Every recording also has a maxDurationSec cap (default one hour). | 3600 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Screencast MCP: record the Windows screen, let the model see it, and edit the result with ffmpeg. Targets (capture tools): full | monitor: | window: | window:exe=<app.exe> | window:hwnd= | region:,,,. list_targets returns ready-made target strings. Capture: screenshot for a still; start_recording -> (do the task) -> stop_recording for video (events: true also logs clicks for read_events and zoom). For flaky failures, start_recording { replayBufferSec } keeps a rolling buffer and save_replay writes the last seconds after the fact. pause_recording/resume_recording skip setup; backend ddagrab uses the GPU. Never start a recording the user did not ask for. Look: contact_sheet is the cheapest overview, sample_frames (mode scenes) for detail, find_text for OCR and secret finding, wait_for_change instead of sleeping, screen_diff to compare two states. Long recording: index_recording once, then search_recording finds moments as text. Edit: prefer one pipeline call (trim, crop, scale, speed, cut_idle, redact, callout, keystroke_overlay, reframe, zoom, backdrop, audio, burn_subtitles, then export_preset or export_gif) over chaining single-edit tools; each tool call re-encodes. To polish a raw recording, start from pipeline recipe pr_demo, tutorial or social_reel (dryRun shows its steps). trim = one segment, clip = several files; export_gif for size-bounded GIF/WebP, compress for a smaller mp4. Produce: callout, zoom, keystroke_overlay, cursor, backdrop, overlay, compose, title_card, xfade_transition, assemble_highlights, burn_subtitles, export_preset. Bug reports: bug_report turns a recording (path or sessionId) into one redacted folder: clip, GIF, contact sheet, steps from the event log, OCR'd error text, environment, and report.md. Markers: add_marker stamps a labelled moment during a recording (or at a second of a file). chapters writes markers, scene changes, or a transcript as mp4/mkv chapters plus YouTube text. pipeline chapters: true keeps markers as chapters through trims and speed. Audio: extract_audio, normalize_audio, denoise, music_bed, narrate (offline voiceover); transcribe makes an SRT for burn_subtitles (words: true for word timing, then cut_by_transcript cuts by quoting it). Outputs go under SCREENCAST_HOME unless a call names a path; times are seconds and positions video pixels. Screen content can include secrets: redact (find_text redact: true -> redact_region) before sharing. doctor diagnoses a missing ffmpeg feature.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": true
} |
| resources | {
"subscribe": true,
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| start_recordingA | Start a background screen recording. Returns a session id; finalize it with stop_recording. Never auto-starts. |
| stop_recordingA | Stop a recording gracefully so the file is finalized; returns the path and duration. |
| delete_recordingA | Delete a finished recording with its sidecars (event log, webcam, transcript, index, markers, pause parts) and registry entries; reports bytes freed. Asks the user first when the client supports it. Edits made from it are kept. |
| pause_recordingA | Pause a recording; until resume_recording nothing is captured, and the gap is left out of the file, events, and markers. |
| resume_recordingA | Resume a paused recording (same target and settings). |
| save_replayA | Save the last N seconds of a replay buffer (start_recording replayBufferSec) to an mp4; the buffer keeps running. |
| list_sessionsA | List all recording sessions (active and finished) with their status, target, output path, and whether the process is still alive. |
| get_sessionA | Inspect a single recording session by id, including live status and whether its output file exists on disk. |
| read_eventsA | Read the input events (clicks, scroll, cursor, shortcuts, typing bursts) of a recording made with events: true, in video seconds and pixels; e.g. types: ['down'], then sample_frames there. |
| add_markerA | Mark a labelled moment on a recording, live or at a second. Kept in the session and a sidecar; chapters and pipeline turn markers into chapters. |
| review_recordingA | Open a recording for a person to review: in MCP Apps clients an inline player to scrub, trim, and redact, then export; elsewhere just the video's details. |
| screenshotB | Capture one PNG of the screen, a monitor, a window, or a region, returned inline and by path. |
| sample_framesA | Sample PNG frames from a video (by fps, timestamps, or scene changes) and return the first few inline so the model can see what happened. |
| contact_sheetB | Tile timestamped frames of a video into one image to see a whole recording at a glance (the cheapest first look). |
| screen_diffA | Compare two screenshots or frames: SSIM score, changed share, and changed boxes in b's pixels, to check a UI change happened only where expected. |
| wait_for_changeA | Wait until part of the screen changes, settles, or shows (or loses) some text, instead of guessing a sleep. Returns the elapsed time, changed regions (screenshot pixels; add |
| find_textA | OCR (built into Windows) on the screen, an image, or video frames, with line and match boxes in image pixels (add |
| index_recordingA | Build a recording's text timeline (.index.json: OCR per scene, events, markers, transcript) for search_recording. |
| search_recordingA | Search an index_recording timeline (screen text, events, markers, transcript): timecoded hits, best first, secrets masked. No frames unless asked. No input: search all indexes. |
| get_media_infoA | Probe a media file with ffprobe and return duration, resolution, frame rate, codecs, container format, and size. |
| trimA | Cut a video down to one sub-clip by start + (end or duration). For several segments use clip; to combine with other edits use pipeline. |
| concatA | Join videos end to end with hard cuts: stream copy when they match, else a re-encode ( |
| convertA | Convert media to mp4, webm, or gif. For a size-bounded GIF/WebP prefer export_gif; for a smaller mp4, compress or export_preset. |
| export_gifA | Export an animated GIF or WebP that fits a size budget (for PRs, issues, READMEs), stepping fps, width, and quality down until it fits. |
| cropB | Crop a video to a pixel rectangle; one running off the frame is rejected. |
| scaleA | Resize a video to a target width and/or height and re-encode. Provide one side to keep the aspect ratio, or both to set an exact size. |
| speedB | Change playback speed, or fast-forward ranges, and re-encode. Audio is retempo'd to match. |
| overlayA | Composite an image or video (logo, watermark, picture-in-picture) onto a video at a pixel position, optionally scaled and time-limited; keeps the base's audio and length. |
| composeA | Lay 2-9 videos out side by side, stacked, or in a grid (before/after, app and terminal), labelled and in sync. |
| perf_overlayA | Draw a recording's CPU or memory track as a small chart with a moving playhead (spikes in red). |
| translate_subtitlesA | Translate an SRT without breaking its timing: call once for the numbered cues, translate them, then call with translations to write ..srt for chapters' subtitleTracks. |
| calloutA | Annotate a video or screenshot with timed boxes, text labels, and arrows. Fallback fonts used are listed in fallbackFonts; characters no font covers are reported in warnings. |
| keystroke_overlayA | Burn keycast-style badges for shortcuts, clicks, and typing from the recording's input event log (start_recording events: true). Never shows typed text: the log has none. |
| cursorA | Draw a smoothed, scaled cursor that hides when idle from the event log of a start_recording cursor: "events" recording (no OS cursor in the video), with click ripples and an optional spotlight. |
| backdropA | Frame a video or screenshot on a gradient, color, or wallpaper with padding, rounded corners, and a drop shadow, optionally on a 16:9/1:1/9:16/4:5 canvas. |
| compressA | Re-encode a video smaller (H.264 CRF ladder, optional width cap). For a platform target use export_preset. |
| extract_audioA | Extract the audio track of a media file to its own file (mp3, aac, wav, or copy). Returns the output path. |
| normalize_audioA | Normalize loudness to a delivery target (two-pass EBU R128 loudnorm); video is copied. Reports loudness before and after. |
| denoiseA | Reduce steady background noise (fan, hum, hiss) in a recording's audio with an adaptive FFT denoiser. Video is copied untouched. Returns the output path. |
| transcribeA | Transcribe a recording's speech to an SRT subtitle file, locally, with FFmpeg 8's whisper filter (needs a whisper.cpp model file). Returns the SRT path and the text. Pair with burn_subtitles to caption the video. |
| burn_subtitlesA | Burn SRT/ASS subtitles (e.g. from transcribe) into a video in the bundled font. |
| chaptersA | Write chapters (markers, scene changes, transcript, or a list) into an mp4/mkv/mov copy without re-encoding; returns YouTube chapter text. Can mux an SRT as soft subtitles. |
| clipA | Extract several frame-exact segments, each to its own file. For one segment, trim does the same. |
| cut_idleA | Remove dead air: cut stretches where the screen is frozen (and silent), keeping a short pad. Returns the time saved. |
| cut_by_transcriptA | Edit a video by its transcript: cut quoted text, cue numbers, or fillers. Also writes the re-timed .srt. |
| redact_regionA | Cover given rectangles in a video or screenshot (e.g. secrets on screen). Not automatic detection: find them with find_text redact: true. Off-frame regions are rejected. |
| list_audio_devicesA | List DirectShow audio devices and flag a likely loopback (Stereo Mix or a virtual-audio driver), for start_recording's audio.device. |
| list_video_devicesA | List DirectShow cameras for start_recording's webcam.device. |
| list_targetsA | List the desktop, monitors, and visible windows (topmost first, with capturability per backend). Each entry has a |
| doctorA | Check the setup: ffmpeg/ffprobe (FFmpeg 8+?), optional filters, capture devices, Windows OCR, settings, and enabled toolsets; |
| xfade_transitionA | Join two videos with an xfade transition (audio crossfaded); they need not match in size, fps, or audio. For more clips use assemble_highlights. |
| assemble_highlightsB | Stitch clips (including title cards) into one video with cuts or xfade transitions; they need not match in size, fps, or audio. |
| title_cardA | Generate a title card clip (centered text on a solid background, silent audio track) to stitch in with assemble_highlights. Uncoverable characters are reported in warnings. |
| music_bedA | Lay music under a video: looped or trimmed to length, faded, leveled, and mixed with any existing audio. Video is stream-copied. |
| narrateA | Offline voiceover with the built-in Windows voices: speaks each line at its time or marker over the audio, plus an SRT. |
| reframeA | Re-aspect a video to 16:9, 9:16, 1:1, or 4:5 by padding or cropping. |
| zoomA | Smooth animated zoom-and-pan into the action and back out, from keyframes or planned from logged clicks or screen changes. |
| pipelineA | Run several edits (trim, crop, scale, speed, cut_idle, redact, callout, keystroke_overlay, cursor, reframe, zoom, backdrop, audio, burn_subtitles, then optionally export_preset or export_gif) in one ffmpeg pass: one re-encode, no intermediate files. Prefer it over chaining edit tools; a recipe does the usual polish in one call. |
| export_presetB | Encode a platform-ready H.264 file (aspect, fps, bitrate, faststart) for a named platform. |
| bug_reportA | Package a recording as a paste-ready repro folder: secret-scanned, redacted clip and GIF, contact sheet, steps from the event log, OCR'd errors, environment, report.md for gh issue create --body-file. |
| step_guideA | Turn a recording's event log into a numbered how-to: a ringed screenshot and caption per step, marker headings; Markdown and/or one HTML file. Never includes typed text. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| bug-repro-clip | Record a target, find the bug moment, redact secrets, trim, annotate, and export a GIF for an issue. |
| file-bug-report | Record a repro with input events, then package it with bug_report: redacted clip, GIF, steps, error text, and report.md. |
| demo-gif | Record a feature walkthrough and export a GIF small enough for a README or PR. |
| verify-ui-change | Screenshot before, make the change, wait for the screen to settle, diff, and check the text. |
| review-recording | Summarize what happens in a recording, with timestamps, using a contact sheet and scene frames. |
| document-steps | Record a task with input events and markers, then turn it into a step-by-step guide with step_guide. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| review-player | Interactive player: scrub, trim, and draw redaction boxes on a recording. |
| sessions | Every recording session (active and finished), newest first. |
TDQS
Scored across 61 tools
Descriptions are unusually good at cross-referencing (e.g. trim vs clip, concat vs xfade_transition vs assemble_highlights, convert vs export_gif vs compress vs export_preset), but the set contains many adjacent-purpose clusters, so misselection is a real risk. Trim/clip, the three join tools, four encode/export tools, and cut_idle/cut_by_transcript all require close reading to pick correctly.
Mostly lower_snake_case, but the pattern mixes verb_noun (start_recording, read_events, cut_idle, save_replay) with bare nouns (speed, chapters, pipeline, cursor, backdrop, screenshot, doctor). Still readable, but no single predictable convention.
61 tools is far above a well-scoped set; the surface spans recording, capture, editing, audio, export, and reporting, so the domain is broad, but the sheer count makes tool selection expensive for an agent. Toolset gating helps conceptually but the exposed surface is still heavy.
Coverage is extensive: full recording lifecycle (start/pause/resume/stop/delete/replay), sessions, markers, indexing/search, capture, editing, audio, export presets, and reporting (bug_report, step_guide), plus device listing and doctor diagnostics. Minor gaps like session renaming/settings management or live streaming are workable around.