How do I use screen-recorder-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@screen-recorder-mcp Record my screen to ~/Desktop/demo.mp4" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

screen-recorder-mcp

by jakubkrzysztofsikora

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

screen-recorder-mcp

MCP server that gives Claude and AI agents start/stop control over full-screen recordings on macOS — powered by FFmpeg avfoundation.

What Is This?

This is a Model Context Protocol (MCP) server that wraps macOS screen recording via FFmpeg's avfoundation input. It lets Claude, or any MCP-compatible AI agent, start and stop full-desktop screen recordings with a simple tool call — no manual terminal commands needed.

Perfect for recording demos, bug reproductions, or documentation walkthroughs driven entirely by AI.

Related MCP server: gnome-screencast-mcp

Demo

You:    "Record my screen to ~/Desktop/demo.mp4 in high quality"
Claude: calls start_recording(output_path: "~/Desktop/demo.mp4", quality: "high")
        "Recording started! Screen index: 1, FPS: 30, Quality: high."

        ... you do the demo ...

You:    "Stop the recording"
Claude: calls stop_recording()
        "Recording stopped. Saved to ~/Desktop/demo.mp4 (34s, 12.8 MB)"

Prerequisites

Requirement	How to get it
macOS 12+	Monterey or later
FFmpeg	`brew install ffmpeg`
Node.js 18+	`brew install node` or nodejs.org
Screen Recording permission	System Settings (see Permissions Setup)

Installation

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "screen-recorder": {
      "command": "npx",
      "args": ["screen-recorder-mcp"]
    }
  }
}

Then restart Claude Desktop.

Claude Code

Add as an MCP server — works immediately without restart:

claude mcp add screen-recorder -- npx screen-recorder-mcp

Then in any Claude Code conversation:

You: "List my screen devices"
You: "Start recording my screen"
You: "Stop the recording"

To remove:

claude mcp remove screen-recorder

Global Install

npm install -g screen-recorder-mcp

Cursor / VS Code / Other MCP Clients

Add to your MCP client's configuration file (e.g., .cursor/mcp.json, .vscode/mcp.json):

{
  "mcpServers": {
    "screen-recorder": {
      "command": "npx",
      "args": ["screen-recorder-mcp"]
    }
  }
}

Smithery Registry

This server is listed on Smithery for one-click installation in compatible MCP clients.

Permissions Setup

Screen recording on macOS requires explicit user consent:

Open System Settings
Navigate to Privacy & Security > Screen Recording
Enable your terminal application (Terminal, iTerm2, Warp, VS Code, etc.)
Restart the terminal application after granting permission

Note: If recording fails with a permission error, the tool returns a structured error with these exact instructions.

Available Tools

Tool	Description	Key Params
`start_recording`	Start full-screen recording	`output_path`, `screen_index`, `audio_index`, `fps`, `quality`, `preset`
`stop_recording`	Stop active recording	(none)
`get_recording_status`	Check if recording is active	(none)
`list_recordings`	List all past recordings	`limit`
`list_screen_devices`	Discover screens & audio devices	(none)

`start_recording`

Start recording the macOS desktop. Only one recording can be active at a time.

Parameter	Type	Default	Description
`output_path`	string	auto-generated	Output `.mp4` file path. Relative paths resolve to `~/Movies/screen-recordings/`
`screen_index`	number	primary display	avfoundation device index (use `list_screen_devices` to find)
`audio_index`	number	none	Audio device index. Omit for no audio, `-1` to explicitly disable
`fps`	number	`30`	Frames per second (1-60)
`quality`	string	`"medium"`	`"low"` (CRF 35), `"medium"` (CRF 28), `"high"` (CRF 18)
`preset`	string	`"ultrafast"`	FFmpeg preset: `ultrafast`, `superfast`, `veryfast`, `faster`, `fast`

{
  "success": true,
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "output_path": "/Users/you/Movies/screen-recordings/recording-2025-03-22-143012.mp4",
  "message": "Recording started. Screen index: 1, FPS: 30, Quality: medium. Use stop_recording to end."
}

`stop_recording`

Stop the active recording. Sends a graceful q signal to FFmpeg and waits for the file to finalize.

{
  "success": true,
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "output_path": "/Users/you/Movies/screen-recordings/recording-2025-03-22-143012.mp4",
  "duration_seconds": 47,
  "file_size_bytes": 15234048,
  "file_size_human": "14.5 MB",
  "message": "Recording stopped. File saved to ... (47s, 14.5 MB)"
}

`get_recording_status`

Check whether a recording is in progress, and get elapsed time.

{
  "status": "recording",
  "is_recording": true,
  "current_session": { "id": "...", "startedAt": "...", "outputPath": "..." },
  "elapsed_seconds": 23,
  "total_recordings": 5
}

`list_recordings`

Returns past recordings sorted by most recent first.

Parameter	Type	Default	Description
`limit`	number	`20`	Max recordings to return

`list_screen_devices`

Discover available screens and audio devices. Run this first if you're unsure which screen_index or audio_index to use.

{
  "screen_devices": [
    { "index": 1, "name": "Capture screen 0", "type": "screen" },
    { "index": 2, "name": "Capture screen 1", "type": "screen" }
  ],
  "audio_devices": [
    { "index": 0, "name": "Built-in Microphone", "type": "audio" },
    { "index": 1, "name": "BlackHole 2ch", "type": "audio" }
  ],
  "recommended_screen_index": 1,
  "ffmpeg_version": "6.1.2"
}

Use Cases

AI-Driven Demo Recording

Let Claude record polished product demos while you narrate and click through the UI. Ask it to start, pause at key moments, and stop — all through natural conversation.

Automated Bug Reproduction

Have Claude record your screen while you reproduce a bug, then reference the recording when filing issues. Especially useful in QA workflows where evidence is required.

Documentation Walkthroughs

Record step-by-step tutorials with Claude managing the recording lifecycle. Combine with voice narration for instant how-to videos.

CI/CD Visual Testing

Integrate screen recordings into automated test pipelines to capture visual regressions or end-to-end test flows.

Pair Programming Sessions

Record your coding sessions with Claude Code as a pair programming partner. Review recordings later to document architectural decisions.

Usage Examples

Record a demo:

"Start recording my screen to ~/Desktop/demo.mp4, high quality" ... do the demo ... "Stop the recording and tell me the file size"

Record with audio:

"List my screen devices, then start recording screen 1 with my built-in microphone"

Multi-monitor:

"List screen devices, start recording the second monitor"

Low-resource recording:

"Start a screen recording at 15 fps, low quality, ultrafast preset"

Check what's recording:

"What's the current recording status? How long has it been going?"

Review past recordings:

"List my last 5 recordings with their file sizes"

Error Handling

All tools return structured errors with resolution hints — they never throw unhandled exceptions to the MCP client:

{
  "success": false,
  "error_type": "ScreenRecordingPermissionError",
  "error": "Screen Recording permission not granted.",
  "resolution": "Open System Settings > Privacy & Security > Screen Recording > enable your terminal app."
}

Error Type	Cause	Resolution
`FfmpegNotFoundError`	ffmpeg not in PATH	`brew install ffmpeg`
`ScreenRecordingPermissionError`	macOS permission denied	Enable in System Settings
`RecordingAlreadyActiveError`	Tried to start while recording	Call `stop_recording` first
`NoActiveRecordingError`	Tried to stop with nothing active	Check `get_recording_status`
`InvalidOutputPathError`	Bad file path or extension	Use a path ending in `.mp4`

Troubleshooting

Problem	Solution
"ffmpeg not found"	`brew install ffmpeg`
"Permission denied" / blank recording	Grant Screen Recording permission in System Settings
Recording starts but file is 0 bytes	Wrong avfoundation device index — use `list_screen_devices`
No audio in recording	Add `audio_index` param — use `list_screen_devices` to find device
High CPU during recording	Use `preset: "ultrafast"` and lower `fps`

How It Works

Claude (MCP Client)          screen-recorder-mcp           FFmpeg
        |                            |                        |
        |-- start_recording -------->|                        |
        |                            |-- spawn ffmpeg ------->|
        |                            |   -f avfoundation      |
        |                            |   -i "3:none"          |
        |                            |   -vcodec libx264      |
        |<-- session_id, path -------|   recording...         |
        |                            |                        |
        |-- stop_recording --------->|                        |
        |                            |-- stdin: "q\n" ------->|
        |                            |          (graceful)     |
        |                            |<-- exit 0 -------------|
        |<-- duration, size ---------|                        |

Development

git clone https://github.com/jakubkrzysztofsikora/screen-recording.git
cd screen-recorder-mcp
npm install

npm run dev          # Run server in dev mode (tsx)
npm test             # Run unit tests
npm run test:coverage # Run tests with coverage report
npm run typecheck    # TypeScript strict mode check
npm run build        # Build to dist/
npm run check-deps   # Verify ffmpeg + list devices
npm run inspect      # Open MCP Inspector

Project Structure

src/
  index.ts       # MCP server entry point & tool registration
  recorder.ts    # FFmpeg process management (start/stop/status)
  devices.ts     # avfoundation device discovery
  storage.ts     # Recording file registry (in-memory + disk manifest)
  types.ts       # All shared TypeScript types & error classes
tests/
  recorder.test.ts
  devices.test.ts
  storage.test.ts

Contributing

See CONTRIBUTING.md for development setup, coding standards, and PR checklist.

License

MIT

Available Tools

5 tools

get_recording_statusA

Get the current recording status. Returns whether a recording is active, current session details if recording, and total count of past recordings.

Inputs: no named parameters.

list_recordingsA

List all recordings captured in this session and from the persistent manifest. Includes file path, duration, size, and timestamp for each recording.

Inputs: limit.

list_screen_devicesA

List all available screen and audio capture devices detected by FFmpeg avfoundation. Use the index values when calling start_recording. Run this first if you're unsure which screen_index to use.

Inputs: no named parameters.

start_recordingA

Start recording the full macOS desktop to a video file. Records all connected screens (by default the primary display) using FFmpeg avfoundation. Only one recording can be active at a time. Returns a session ID and output path. Requires Screen Recording permission granted to this terminal app in System Settings.

Inputs: fps, preset, quality, audio_index, +2 more.

stop_recordingA

Stop the currently active screen recording. Sends a graceful shutdown signal to FFmpeg and waits for the file to be finalized. Returns the completed recording session details including duration and file size.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored 2026-09-06 08:20 across 5 tools

Disambiguation5/5

Each tool maps to a distinct lifecycle concern: starting, stopping, querying active status, listing recorded files, and enumerating capture devices. There is no functional overlap between any pair.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern with clear verbs: start, stop, get, list. The naming style is uniform and predictable.

Tool Count5/5

Five tools is well-scoped for a screen recorder: no redundant helpers or missing essentials. Each tool earns its place in the workflow.

Completeness5/5

The domain of screen recording is covered end-to-end: device discovery, start, stop, status, and listing past recordings. There are no obvious dead ends or missing operations for this use case.

Maintenance

ActivityInactive

ResponsivenessOutdated data

Resources

Related MCP Connectors

KinoPipe
io.github.nicolascoutureau
FFmpeg as a service for AI agents: typed video editing tools, async jobs, downloadable outputs.
Multimedia Processing Image & Video Processing
1
https://kinopipe.com/mcp
Rendobar
com.rendobar
Transform video, audio and images, and generate media from prompts. FFmpeg, captions, models.
Multimedia Processing Image & Video Processing
21
https://api.rendobar.com/mcp
Agent-Native Clips
io.github.BuilderIO
Screen recording, meeting notes, and voice dictation - all with AI
Speech Processing Note Taking Multimedia Processing
14,698
https://clips.agent-native.com/mcp
mcpA
online.editclips
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
Multimedia Processing Audio Processing Image & Video Processing
51
https://editclips.online/mcp

Related MCP Servers

video-capture-mcp
Multimedia Processing Image & Video Processing Testing & QA Tools
Corvus400
A
license
A
quality
C
maintenance
MCP server for screen recording on macOS, iOS Simulator, and Android, with key-frame extraction via ffmpeg, enabling AI agents to capture UI motion and transient visual states.
Updated 5 months ago (2026-06-05 22:04 UTC)
12
1
MIT
gnome-screencast-mcp
Multimedia Processing Developer Tools
quinho981
A
license
A
quality
C
maintenance
Enables AI agents to start and stop native GNOME Shell screen recordings via MCP tools, returning JSON with file path, size, and duration without depending on ffmpeg or wf-recorder.
Updated 3 months ago (2026-08-24 20:29 UTC)
3
MIT
agentcastkit
Autonomous Agents Multimedia Processing
obaid
A
license
Not graded
quality
C
maintenance
Enables AI agents to create and manage macOS screen recordings through a semantic demo plan, including permission checks, source listing, and durable recording jobs.
Updated 2 months ago (2026-08-31 13:41 UTC)
13 npm
Apache 2.0
TutorialFlow
Multimedia Processing Image & Video Processing Text-to-Speech
smshozab
A
license
Not graded
quality
B
maintenance
Enables users to turn screen recordings into narrated tutorials by providing visual evidence to ChatGPT, then rendering the final video, audio, script, and thumbnail using FFmpeg and ElevenLabs.
Updated a month ago (2026-10-02 23:43 UTC)
3
MIT

screen-recorder-mcp

What Is This?

Demo

Prerequisites

Installation

Claude Desktop

Claude Code

Global Install

Cursor / VS Code / Other MCP Clients

Smithery Registry

Permissions Setup

Available Tools

start_recording

stop_recording

get_recording_status

list_recordings

list_screen_devices

Use Cases

AI-Driven Demo Recording

Automated Bug Reproduction

Documentation Walkthroughs

CI/CD Visual Testing

Pair Programming Sessions

Usage Examples

Error Handling

Troubleshooting

How It Works

Development

Project Structure

Contributing

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

video-capture-mcp

gnome-screencast-mcp

agentcastkit

TutorialFlow

`start_recording`

`stop_recording`

`get_recording_status`

`list_recordings`

`list_screen_devices`