How do I use screen-recorder-mcp?

1. Click on "Install 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 Related Servers Score Discussions

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: ffmpeg-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

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jakubkrzysztofsikora/screen-recording'

If you have feedback or need assistance with the MCP directory API, please join our Discord server