screen-recorder-mcp

An MCP server that lets an AI assistant record a video of one app window, a part of it, or a whole monitor. Works on Windows and macOS.

Window recordings only contain the chosen app. If another window is dragged over it, the recording keeps showing the app underneath, not the window on top.

You:    record the Chrome window for the demo, just the left half
Claude: [calls list_targets, pick_region, start_recording]
        Recording Chrome. Tell me when to stop.
You:    stop
Claude: Saved ~/Videos/screen-recorder-mcp/rec-20261021-153000.mp4 (42 s)

Features

• Record a single window (by title, app name or id) or a whole monitor.

• Windows in front of the recorded app don't show up in the video.

• Crop: an overlay lets you drag a rectangle over the app to record only that part.

• Optional audio, off by default: system sound or microphone.

• Constant frame rate MP4 (H.264), even when the app isn't redrawing.

• Works without the GPU on Windows: if the GPU can't start a capture session (out of video memory, busy with a render or a game), it falls back to CPU capture on its own. You can also force it.

• Optional desktop app laid out like the Windows Snipping Tool: selection overlay, recording toolbar with pause, player with trim, GIF export, history and settings. When the app is open, the AI records through it, so you always see the toolbar (with an "AI" badge) and can stop it.

• Plain stdio MCP server, so any MCP client can use it (Claude Code, Claude Desktop, Cursor, ...).

Related MCP server: screen-mcp-server

Platform support

Linux isn't supported yet. The OS-specific code sits behind one interface (src/screen_recorder_mcp/backends/), so adding it is mostly a matter of writing a new backend.

Requirements

• Python 3.11+ and uv

• ffmpeg on your PATH

  • Windows: winget install ffmpeg

  • macOS: brew install ffmpeg

• The region picker uses tkinter. uv's managed Python includes it; Homebrew's Python often doesn't.

Install

git clone https://github.com/gcamara/screen-recorder-mcp.git
cd screen-recorder-mcp
uv sync

macOS permissions

Give Screen Recording permission to the app that launches the server (Terminal, iTerm, the Claude desktop app, ...) in System Settings > Privacy & Security, then restart that app. audio="mic" also needs Microphone.

Desktop app

uv run screen-recorder

It sits in the tray. + New (or Ctrl+Shift+R) opens the selection overlay:

• Window: hover and click a window. Only that app is recorded, even if something covers it.

• Rectangle: drag an area of the screen. This is a screen region, so whatever is on top of it is recorded too.

• Full screen: click a monitor.

Pick a delay (3, 5 or 10 s) in the toolbar if you need time to get ready. While recording:

• a border frames what is being recorded (it follows the window in Window mode);

• the recording bar sits at the top of the screen with pause, stop, discard and the mic / system-audio toggles. Drag it anywhere; it remembers the spot. Neither the bar nor the border is ever part of the video.

When you stop, the recording is copied to the clipboard (turn this off in Settings) and opens in the player: trim the start and end, export a GIF, save, open the folder, or copy it again as video, GIF or file path (also on right-click in the history). Recent in the toolbar, and in the tray menu, lists the latest recordings; settings are under the gear.

How the app and the MCP server fit together

you ──▶ desktop app (tray, overlay, toolbar, player) ──┐
                                                         ├──▶ recording service (one owner)
AI ───▶ MCP server ──── localhost + token ──────────────┘
         └─ app not running? records on its own, as before

The app writes control.json (port + random token) to your user's app-data folder and only accepts local connections that carry the token. The MCP server checks for it on every call: if the app is running, recordings go through the app (toolbar, history, settings are shared); if not, the MCP server records by itself. Recordings you make by hand show up in list_recordings, so you can tell the AI "make a GIF of my last recording".

Connect it to your AI client

Replace /path/to/screen-recorder-mcp with where you cloned it.

Claude Code

claude mcp add screen-recorder --scope user -- uv --directory /path/to/screen-recorder-mcp run --no-sync screen-recorder-mcp

Claude Desktop, Cursor and other clients (mcpServers section of the client's config):

{
  "mcpServers": {
    "screen-recorder": {
      "command": "uv",
      "args": ["--directory", "/path/to/screen-recorder-mcp", "run", "--no-sync", "screen-recorder-mcp"]
    }
  }
}

Restart the client and the tools below show up.

--no-sync matters on Windows: plain uv run re-installs the package when dependencies change, and that fails while another client session has the server's .exe open. After pulling a new version, close your AI clients and run uv sync once.

Usage

Just ask in plain language:

• "Record the Notepad window for 30 seconds."

• "Record my second monitor with the microphone on."

• "Record the YouTube tab." The site is matched against the browser window's title, so that tab has to be the active one.

• "Start recording." The assistant lists your windows and asks which one, then asks whether you want to crop.

The server tells the assistant to:

1. use the screen, app or site you named, or ask you which one when you didn't;

2. ask whether you want to record only part of it, and if so open the crop overlay;

3. leave audio off unless you asked for it.

Crop overlay: drag a rectangle, then press Enter or double-click to confirm. Esc or right-click records the whole window.

Tools

target accepts a window title or part of it, an app name (chrome, notepad.exe, Safari), a window_id from list_targets, or monitor:N.

capture picks how frames are read: "auto" (GPU, falling back to CPU), "gpu", or "cpu" (Windows only). Ask for it in plain words, e.g. "record Chrome, use the CPU, my GPU is busy". CPU capture doesn't draw the mouse cursor and costs more CPU per frame.

Files are saved to ~/Videos/screen-recorder-mcp/ on Windows and ~/Movies/screen-recorder-mcp/ on macOS, unless you pass output_dir.

Limitations

• A minimized window produces no frames. start_recording fails with a message saying so.

• On Windows, audio="system" records every app's sound, not only the recorded one.

• Recording a whole monitor captures whatever is on it, including windows on top.

• Some apps block capture of their windows (DRM video, some password managers). Those come out black.

• One recording at a time (shared between the app and the AI).

• The app's global shortcut is Windows-only for now; on macOS open the app from the tray.

How it works

OS capture API ──frames on change──▶ latest-frame slot ──▶ pacer (fixed fps) ──▶ ffmpeg ──▶ MP4
 (WGC / SCK)                                                  crop + size lock
optional audio ──▶ WAV (silence-padded) ─────────────────────────────── mux ──▶ final MP4

• Per-window capture. Windows Graphics Capture and ScreenCaptureKit both read the window's own surface from the compositor, not the pixels on screen. That's why windows on top don't appear. The CPU path on Windows asks the window to paint itself into a bitmap (PrintWindow), which keeps the same guarantee, and stretches windows that aren't DPI-aware the way the desktop shows them.

• Constant frame rate. Both APIs only send a frame when the window changes, so a static window would produce a 10-second video only a fraction of a second long. A pacer thread re-sends the latest frame on a fixed clock.

• Size lock. The output size is fixed from the first frame. If the window is resized later, frames are padded or trimmed to that size, because ffmpeg's raw input needs a constant size.

• Audio gaps. System/app audio sends no packets while nothing is playing. The WAV writer fills those gaps with silence so the audio stays in sync with the video.

• stdout stays clean. In a stdio MCP server stdout carries the protocol. ffmpeg's output goes to a log file, and the crop overlay runs in its own process.

Development

uv run pytest -q                                      # unit tests, no desktop needed
uv run python scripts/verify_recording.py notepad     # real recording on this machine
uv run python scripts/verify_recording.py notepad --capture=cpu

verify_recording.py records a window while a red window covers it, then checks the result with ffprobe: duration, even dimensions, no red in the frames, and an audio stream when audio is on. On macOS use TextEdit as the window. If you have a Mac, running it there and reporting the output is the most useful contribution right now.

Layout:

src/screen_recorder_mcp/
  server.py            MCP tools
  recorder.py          one recording session (capture → pacer → encoder, audio, mux)
  frame_pacer.py       constant-fps pacing
  region_picker.py     crop overlay (runs as a subprocess)
  frame_sources.py     polling source + GPU→CPU fallback
  backends/windows/    Win32 window list, WGC capture, GDI CPU capture, WASAPI audio
  backends/macos/      Quartz window list, ScreenCaptureKit capture and app audio

License

MIT