# @tmhs/screencast-mcp [Health: Active]

**Category:** 🎥 Multimedia Process  
**Repository:** https://github.com/TMHSDigital/screencast-mcp  
**GitHub Stars:** 1  
**npm Downloads (last month):** 5062  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/tmhs-screencast-mcp

## Description
Let AI agents record the Windows screen, watch it as frames, and edit it with ffmpeg

## Tools
Capabilities this server exposes over MCP:

- **start_recording** — Start a background screen recording. Returns a session id; finalize it with stop_recording. Never auto-starts.
- **stop_recording** — Stop a recording gracefully so the file is finalized; returns the path and duration.
- **delete_recording** — 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_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. Kept in the session and a sidecar; chapters and pipeline turn markers into chapters.
- **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.
- **screenshot** — Capture one PNG of the screen, a monitor, a window, or a region, returned inline and by path.
- **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. Returns the elapsed time, changed regions (screenshot pixels; add `origin` for desktop), and the final state.
- **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). Locate UI text or secrets (e.g. regex 'sk-|ghp_|api.?key') to redact. Best-effort: review results.
- **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. No frames unless asked.
- **get_media_info** — Probe a media file with ffprobe and return duration, resolution, frame rate, codecs, container format, and size.
- **trim** — 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.
- **concat** — Join videos end to end with hard cuts: stream copy when they match, else a re-encode (`mode` says which). For transitions use xfade_transition or assemble_highlights.
- **convert** — 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_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. Provide one side to keep the aspect ratio, or both to set an exact size.
- **speed** — Change playback speed by a factor (>1 faster, <1 slower) and re-encode. Audio is retempo'd to match when the source has an audio track.
- **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 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_overlay** — 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.
- **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.
- **compress** — Re-encode a video smaller (H.264 CRF ladder, optional width cap). For a platform target use export_preset.
- **extract_audio** — Extract the audio track of a media file to its own file (mp3, aac, wav, or copy). Returns the output path.
- **normalize_audio** — Normalize loudness to a delivery target (two-pass EBU R128 loudnorm); video is copied. Reports loudness before and after.
- **denoise** — 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.
- **transcribe** — 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_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. Can mux an SRT as soft subtitles.
- **clip** — Extract several frame-exact segments, each to its own file. For one segment, trim does the same.
- **cut_idle** — Remove dead air: cut stretches where the screen is frozen (and silent), keeping a short pad. Returns the time saved.
- **cut_by_transcript** — Edit a video by its transcript: cut quoted text, cue numbers, or fillers. Also writes the re-timed .srt.
- **redact_region** — 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_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). Each entry has a `target` string to pass as-is to capture tools; use it instead of guessing a title.
- **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. Call on first use or when a tool reports a missing feature.
- **xfade_transition** — 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_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. Uncoverable characters are reported in warnings.
- **music_bed** — Lay music under a video: looped or trimmed to length, faded, leveled, and mixed with any existing audio. Video is stream-copied.
- **narrate** — Offline voiceover with the built-in Windows voices: speaks each line at its time or marker over the audio, plus an SRT.
- **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.
- **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. Prefer it over chaining edit tools; a recipe does the usual polish in one call.
- **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. Never includes typed text.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "screencast-mcp": {
    "command": "npx",
    "args": ["-y","@tmhs/screencast-mcp"],
    "env": {
      "SCREENCAST_HOME": "",
      "SCREENCAST_TOOLSETS": ""
    }
  }
}
```

**Requires environment variables:** `SCREENCAST_HOME`, `SCREENCAST_TOOLSETS` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What @tmhs/screencast-mcp does

@tmhs/screencast-mcp connects an MCP-capable agent to desktop video workflows. It can record a full desktop, individual monitor, application window, or selected region on Windows 10 and 11. Recordings are started only through an explicit tool call and return a session identifier for later control.

The distinctive workflow is recording followed by inspection. The agent can sample a recording into viewable frames, check for changes, locate text, compare screen states, and use event information such as clicks to guide later edits. This lets an agent verify what appeared on screen rather than treating the recording as an opaque file.

Editing and production features cover operations such as trimming, cropping, redaction, annotation, click-focused zooming, and exporting clips or GIFs for destinations such as GitHub or social media. FFmpeg and ffprobe provide the media-processing layer.

## How it works

The server communicates over MCP stdio. A typical session starts with `start_recording`, which runs in the background and targets the requested desktop content. `stop_recording` finalizes the file and reports its path and duration; recordings can also be paused and resumed. Finished recordings can be removed with `delete_recording`, including associated sidecar data such as event logs, transcripts, indexes, markers, and pause segments.

`get_media_info` probes a file and reports properties including duration, dimensions, frame rate, codecs, container, and size. The watch-oriented tools can return sampled frames and support checks such as waiting for a screen change, finding text, and producing a screen difference. Capture output is stored under `SCREENCAST_HOME`, rather than in the project checkout.

## Setup and configuration

The quick setup command is:

```text
npx -y @tmhs/screencast-mcp setup
```

Setup checks FFmpeg, OCR, and speech support, can offer installation through `winget`, and can configure Claude Desktop, Claude Code, Cursor, and VS Code. Use `--dry-run` to inspect proposed changes or `--test` to make a short test GIF. The server can also be added manually with an MCP stdio configuration:

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

Manual setup requires Windows 10 or 11 for capture, Node.js 22 or newer, and FFmpeg 8 or newer on `PATH`. The full FFmpeg build is recommended because older or minimal builds may omit filters needed for transcription or specific capture backends. Run `doctor` after connecting to inspect FFmpeg, available filters and devices, OCR, settings, architecture, and enabled toolsets.

## Tools and capabilities

The server provides 59 typed tools organized into six toolsets. Core tools include:

- `doctor` for checking dependencies, devices, optional features, and configuration.
- `get_media_info` for reading media metadata with ffprobe.
- `start_recording`, `stop_recording`, `pause_recording`, and `resume_recording` for controlled capture.
- `delete_recording` for removing a finished recording and its related sidecars.
- `save_replay` for saving the last section of a replay buffer.

Other capabilities include frame sampling, scene-change inspection, OCR-oriented text finding, screen diffs, event-aware editing, redaction, annotations, click highlighting, zoom effects, trimming, cropping, and format export. The available toolsets can be selected with `SCREENCAST_TOOLSETS`; core tools remain loaded regardless of that selection.

## Limitations and notes

Screen capture itself is limited to Windows. The watch, edit, and production functions can run on other operating systems when FFmpeg is available. Capture never begins automatically; an agent must invoke a recording tool.

Windows on ARM64 has partial support depending on the FFmpeg build. Some builds lack Whisper support or the libraries needed for WebM output, and `doctor` reports missing capabilities. The project is licensed under CC BY-NC-ND 4.0, which permits non-commercial use under that license's terms.

_Full upstream README: https://allmcps.com/mcp/tmhs-screencast-mcp/readme_