Give your agent
eyes on the screen.

Name: Screencast MCP
Author: TMHSDigital

FOR Developers who want their coding agent to see and prove UI changes on Windows: bug repros, UI checks, and demo clips the agent records, watches, and edits itself.

screencast-mcp records the Windows screen, samples footage into frames an agent can actually look at, and cuts the result with ffmpeg — from a quick trim to a platform-ready export. It speaks MCP over stdio, so it plugs into any MCP client.

$claude mcp add screencast -- cmd /c npx -y @tmhs/screencast-mcp

Set up Claude Desktop, Cursor, or VS Code See the workflows View the source

This is what the agent sees. Drag along the strip.

sample_frames { "input": "rec.mp4", "timestamps": [0.00] }

Every frame here came from sample_frames on a real recording. The amber mark is where mode: "scenes" picks a frame; the red one is the click read_events logged.

Needs Windows 10 or 11 and ffmpeg / ffprobe on PATH (winget install Gyan.FFmpeg, or set FFMPEG_PATH / FFPROBE_PATH). Capture is Windows-only; the watch and edit tools run anywhere ffmpeg runs. Any other MCP client:

{
  "mcpServers": {
    "screencast": {
      "command": "npx",
      "args": ["-y", "@tmhs/screencast-mcp"]
    }
  }
}

00:01SLATE / WHY NOT JUST…

A recorder the agent drives, not you.

Instead of	The difference
OBS, ShareX, Game Bar	Built for a person at the controls. Here the agent starts and stops the recording, looks at the frames, and makes the edits through typed tools, with no GUI step.
Playwright video	Browser pages only, and the video is a file the model never sees. Here: any window or monitor, frames returned to the model, plus `wait_for_change`, `find_text`, and `screen_diff` to check what happened.
Screenshot-only MCPs	Single stills. Here: video over time, an input event log, scene-change sampling, redaction, and export, so the agent can show a sequence, not one moment.

Capture is Windows-only. The watch, edit, and produce tools work on any OS with ffmpeg, so a Mac or Linux agent can still trim, redact, caption, and export a recording made elsewhere.

00:02CHAPTER 1 / CAPTURE

Point it at anything on screen.

Record the whole desktop, one monitor, a window by title, or an exact pixel region — with optional system audio through a loopback device. Recordings run as background sessions you stop by id; screenshots are one call. Every capture is an explicit tool call: nothing records on its own.

Tool	What it does
`start_recording`	Start a background screen recording.
`stop_recording`	Stop a recording gracefully so the file is finalized; returns the path and duration.
`pause_recording`	Pause a recording; until resume_recording nothing is captured, and the gap is left out of the file, events, and markers.
`resume_recording`	Resume a paused recording (same target and settings).
`save_replay`	Save the last N seconds of a replay buffer (start_recording replayBufferSec) to an mp4; the buffer keeps running.
`list_sessions`	List all recording sessions (active and finished) with their status, target, output path, and whether the process is still alive.
`get_session`	Inspect a single recording session by id, including live status and whether its output file exists on disk.
`read_events`	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_marker`	Mark a labelled moment on a recording, live or at a second.
`screenshot`	Capture one PNG of the screen, a monitor, a window, or a region, returned inline and by path.
`get_media_info`	Probe a media file with ffprobe and return duration, resolution, frame rate, codecs, container format, and size.
`list_audio_devices`	List DirectShow audio devices and flag a likely loopback (Stereo Mix or a virtual-audio driver), for start_recording's audio.device.
`list_video_devices`	List DirectShow cameras for start_recording's webcam.device.
`list_targets`	List the desktop, monitors, and visible windows (topmost first, with capturability per backend).
`doctor`	Check the setup: ffmpeg/ffprobe (FFmpeg 8+?), optional filters, capture devices, Windows OCR, settings, and enabled toolsets; `problems` says what is missing and how to fix it.

00:14CHAPTER 2 / WATCH

Video a model can read.

A video file is opaque to a language model. sample_frames turns footage into PNGs an agent can actually view — at a fixed rate for a full pass, or at exact timestamps to check one moment.

Tool	What it does
`review_recording`	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.
`player_frames`	Preview frames for the review player: JPEGs on an even grid over the video plus frames at scene changes, with their real times.
`sample_frames`	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_sheet`	Tile timestamped frames of a video into one image to see a whole recording at a glance (the cheapest first look).
`screen_diff`	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_change`	Wait until part of the screen changes or settles, instead of guessing a sleep.
`find_text`	OCR (built into Windows) on the screen, an image, or video frames, with line and match boxes in image pixels (add `origin` for desktop coordinates).
`index_recording`	Build a recording's text timeline (<video>.index.json: OCR per scene, events, markers, transcript) for search_recording.
`search_recording`	Search an index_recording timeline (screen text, events, markers, transcript): timecoded hits, best first, secrets masked.

00:26CHAPTER 3 / EDIT

Small cuts, clean errors.

Composable ffmpeg edits with validated inputs — a bad rectangle, an odd dimension, or a wrong duration is rejected with a message that says how to fix it, not an encoder stack trace. Tools that write a file refuse to replace an existing file at a caller-supplied output path unless overwrite: true is passed; auto-generated default paths are always unique.

Tool	What it does
`trim`	Cut a video down to one sub-clip by start + (end or duration).
`concat`	Join videos end to end with hard cuts: stream copy when they match, else a re-encode (`mode` says which).
`convert`	Convert media to mp4, webm, or gif.
`export_gif`	Export an animated GIF or WebP that fits a size budget (for PRs, issues, READMEs), stepping fps, width, and quality down until it fits.
`crop`	Crop a video to a pixel rectangle; one running off the frame is rejected.
`scale`	Resize a video to a target width and/or height and re-encode.
`speed`	Change playback speed by a factor (>1 faster, <1 slower) and re-encode.
`compress`	Re-encode a video smaller (H.264 CRF ladder, optional width cap).
`extract_audio`	Extract the audio track of a media file to its own file (mp3, aac, wav, or copy).
`normalize_audio`	Normalize loudness to a delivery target (two-pass EBU R128 loudnorm); video is copied.
`denoise`	Reduce steady background noise (fan, hum, hiss) in a recording's audio with an adaptive FFT denoiser.
`transcribe`	Transcribe a recording's speech to an SRT subtitle file, locally, with FFmpeg 8's whisper filter (needs a whisper.cpp model file).
`clip`	Extract several frame-exact segments, each to its own file.
`cut_idle`	Remove dead air: cut stretches where the screen is frozen (and silent), keeping a short pad.
`cut_by_transcript`	Edit a video by its transcript: cut quoted text, cue numbers, or fillers.
`redact_region`	Cover given rectangles in a video (e.g. secrets on screen).
`music_bed`	Lay music under a video: looped or trimmed to length, faded, leveled, and mixed with any existing audio.
`narrate`	Offline voiceover with the built-in Windows voices: speaks each line at its time or marker over the audio, plus an SRT.
`pipeline`	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.

00:41CHAPTER 4 / PRODUCE

From raw capture to something you’d publish.

Assembly, titles, music, and platform-shaped exports. Mixed inputs are normalized to a common resolution, fps, and audio rate before they are combined, so heterogeneous clips compose cleanly.

Tool	What it does
`overlay`	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.
`callout`	Annotate a video with timed boxes, text labels, and arrows.
`keystroke_overlay`	Burn keycast-style badges for shortcuts, clicks, and typing from the recording's input event log (start_recording events: true).
`cursor`	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.
`backdrop`	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.
`burn_subtitles`	Burn SRT/ASS subtitles (e.g. from transcribe) into a video in the bundled font.
`chapters`	Write chapters (markers, scene changes, transcript, or a list) into an mp4/mkv/mov copy without re-encoding; returns YouTube chapter text.
`xfade_transition`	Join two videos with an xfade transition (audio crossfaded); they need not match in size, fps, or audio.
`assemble_highlights`	Stitch clips (including title cards) into one video with cuts or xfade transitions; they need not match in size, fps, or audio.
`title_card`	Generate a title card clip (centered text on a solid background, silent audio track) to stitch in with assemble_highlights.
`reframe`	Re-aspect a video to 16:9, 9:16, 1:1, or 4:5 by padding or cropping.
`zoom`	Smooth animated zoom-and-pan into the action and back out, from keyframes or planned from logged clicks or screen changes.
`export_preset`	Encode a platform-ready H.264 file (aspect, fps, bitrate, faststart) for a named platform.
`bug_report`	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_guide`	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.

00:48CHAPTER 5 / WORKFLOWS

Recipes you can paste.

Each one starts from a prompt you would actually type, shows the tool calls it produces, and ends with the real output.

00:52APPENDIX / WINDOWS NOTES

Know your capture surface.

Monitor targets crop the virtual desktop to a display’s real pixel bounds, so monitor:1 grabs the second display at its true offset; monitor:0 is primary.
Window capture matches a case-insensitive exact title first, then falls back to a substring match; with several matches the topmost window wins. To avoid relying on the title, target window:exe=Code.exe (the app's topmost window) or window:hwnd=0x1A2B.
Fullscreen-exclusive apps can produce black frames under gdigrab; use borderless-windowed mode.
backend: "wgc" on start_recording or screenshot captures one window’s own surface through Windows Graphics Capture (FFmpeg 8+): it keeps recording the window while it is covered, moved, or in the background.
System audio capture (start_recording with audio.source = system) needs a virtual-audio loopback device, since gdigrab is video-only and Windows has no native loopback. Use list_audio_devices to find one. Microphone capture is not supported.

00:55APPENDIX / SAFETY

The screen is sensitive. Treat it that way.

Screen capture can record anything on screen, including secrets. Capture is always explicit (a tool call, never automatic), and this public repo ignores captured media so test recordings cannot be committed by accident. The server makes no network requests and has no telemetry; anything a tool returns to your agent (frames, OCR text, event summaries) is sent to your model provider like any other tool result. Review frames before sharing a file, and use redact_region before anything leaves the machine. The optional input event log never records typed text: typing is logged only as bursts on a 0.5 s grid, and at most Ctrl/Alt/Win shortcuts are named. See the README's Privacy section for what is stored and how to delete it.

00:58APPENDIX / LICENSE

Can I use it at work?

screencast-mcp is free under CC BY-NC-ND 4.0: use and share it for non-commercial purposes, with attribution, without distributing modified versions. If your use is commercial (inside a paid product or service, or work done mainly for commercial advantage), or you are not sure, open an issue to ask about a commercial license. The model behind it is in the TMHSDigital licensing standard.

Give your agenteyes on the screen.