Video Capture

macOS, iOS Simulator, and Android screen recording plus key-frame extraction for MCP-aware AI agents.

PyPI CI License: MIT Python macOS

video-capture-mcp gives AI agents a stdio MCP server for recording UI motion while they operate apps, then extracting frames with ffmpeg. It is designed for bugs and requirements that screenshots miss, such as keyboards opening, hover/unhover states, and transient layout glitches.

Features

• 3 OS recording backends in one MCP server: macOS, iOS Simulator, and Android.
• App-window-bounded macOS recording with activation and visible-region checks.
• Manual start/stop recording across macOS, iOS Simulator, and Android.
• Hover sequence API for UI demos that need mouse movement without clicks.
• record_and_extract for one-shot recording plus ffmpeg key-frame extraction.
• FastMCP Image inline responses for extracted frames.

Requirements

• macOS 12 or newer.
• Python 3.11 or 3.12 for PyPI and uvx installs. Homebrew installs its own Python dependency.
• uv for the uvx install method (Option 1), which provides the uvx command. Option 2 (pip, standard CPython pip) and Option 3 (Homebrew) do not require uv. See the Quickstart for the install command, or the uv installation docs.
• ffmpeg and ffprobe.
• Xcode Command Line Tools for iOS Simulator recording.
• Android platform-tools and adb for Android recording.

Installation

You do not need to clone this repository. Pick one install method below. New to MCP? Follow the numbered Quickstart instead: it walks through uv, ffmpeg, registration, and macOS permissions in order.

Option 1: uvx (zero install) [Recommended]

uvx is bundled with uv. If uv is not installed yet, see Quickstart step 1. Then register the server:

Claude Code:

claude mcp add --scope user --transport stdio video_capture -- uvx video-capture-mcp

Claude Desktop:

{
  "mcpServers": {
    "video_capture": {
      "command": "uvx",
      "args": ["video-capture-mcp"]
    }
  }
}

VS Code / Cursor:

{
  "servers": {
    "video_capture": {
      "type": "stdio",
      "command": "uvx",
      "args": ["video-capture-mcp"]
    }
  }
}

Codex:

[mcp_servers.video_capture]
command = "uvx"
args = ["video-capture-mcp"]

Goose:

goose configure --name video_capture --command "uvx video-capture-mcp"

Option 2: pip

python3 -m pip install video-capture-mcp
claude mcp add --scope user --transport stdio video_capture -- video-capture-mcp

Codex:

[mcp_servers.video_capture]
command = "video-capture-mcp"
args = []

Option 3: Homebrew

brew install Corvus400/tap/video-capture-mcp
claude mcp add --scope user --transport stdio video_capture -- video-capture-mcp

Codex:

[mcp_servers.video_capture]
command = "video-capture-mcp"
args = []

Quickstart (Claude Code)

1. Install uv.

   curl -LsSf https://astral.sh/uv/install.sh | sh
   # or: brew install uv
   

   uvx (used below) ships with uv.

2. Install ffmpeg.

   brew install ffmpeg
   

3. Register the MCP server.

   claude mcp add --scope user --transport stdio video_capture -- uvx video-capture-mcp
   

4. Grant macOS Screen Recording permission.

   Recording requires Screen Recording permission. See the macOS Permissions section just below for the exact steps, and run check_macos_permissions from the agent if you are unsure which process to add.

5. Record.

   Ask Claude Code to start recording a visible app window:

   {
     "app_name": "Finder",
     "options": {
       "include_cursor": true
     }
   }
   

   Have the agent operate the UI, then call mcp__video_capture__stop_recording with the returned session_id.

macOS Permissions

See docs/permissions.md for full details.

• Screen Recording is required for start_recording target=macos and start_app_window_recording.
• Accessibility is required for move_pointer and hover_sequence.
• This is a macOS TCC requirement and cannot be granted automatically by an MCP server. It is normally a one-time permission for the process that launches the server, not a per-recording step.
• From Claude Code or Codex, use check_macos_permissions when setup is unclear. It reports whether Screen Recording works, the launcher process macOS is evaluating, the System Settings location, and the required MCP client restart.
• Add the launcher process to System Settings > Privacy & Security > Screen Recording. For uvx and pip, this is usually the Python interpreter for that environment. For Homebrew, it is the installed video-capture-mcp executable.

Tools

Tool	Purpose	Key args
start_recording	Start recording on selected target	target, duration_seconds, options
stop_recording	Stop a session and normalize orientation	session_id
stop_all_recordings	Stop active sessions, optionally by target	target
start_app_window_recording	macOS app-window-bounded recording	app_name, duration_seconds, options
get_window_region	Activate and measure front-window visibility	app_name, min_visible_ratio
hover_sequence	Mouse-move sequence without clicks	points, hold_seconds, app_name
move_pointer	Single mouse-move without click	x, y
extract_frames	ffmpeg scene or fixed-fps frame extraction	video_path, mode, max_frames
record_and_extract	Record and extract in one call	target, duration_seconds, output_dir
list_active_sessions	List current recordings	none
cleanup_stale_processes	Reap recordings from dead previous server PIDs	none
check_macos_permissions	Diagnose macOS Screen Recording permission and setup guidance	none

Detailed parameters and option schemas are in docs/tools.md.

Configuration

• VIDEO_CAPTURE_MCP_OUTPUT_DIR: default output root for recordings when output_path is omitted. Defaults to the system temp directory under video-capture-mcp.

Troubleshooting

See docs/troubleshooting.md for TCC denial, missing ffmpeg, no booted Simulator, and unauthorized adb devices.

Development

See docs/development.md for clone, local install, tests, linting, package build, and the bin/video-capture-mcp from-source wrapper.

Security

See SECURITY.md. Report vulnerabilities through GitHub Private Security Advisories.

Explicit output_path values are treated as trusted MCP client input. Use MCP client approvals and filesystem policy to control where agents may write.

License

MIT. See LICENSE.