Screencast MCP

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:

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:

{
  "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.