video-capture-mcp 0.1.1

MCP server for autonomous macOS, iOS Simulator, and Android screen recording with frame extraction.

video-capture-mcp

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

video-capture-mcp gives AI agents a stdio MCP server for recording short UI flows, checking macOS app-window visibility, moving the pointer for hover demos without clicking, and extracting frames with ffmpeg.

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.
• 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.
• ffmpeg and ffprobe.
• Xcode Command Line Tools for iOS Simulator recording.
• Android platform-tools and adb for Android recording.

Installation

Option 1: uvx (zero install) [Recommended]

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 = []

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.
• Add the executable that launches the server to System Settings > Privacy & Security. For uvx and pip, this is usually the Python interpreter for that environment. For Homebrew, it is the installed video-capture-mcp executable.

Quickstart (Claude Code)

1. Install ffmpeg.

   brew install ffmpeg
   

2. Register the MCP server.

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

3. Ask Claude Code to call mcp__video_capture__start_app_window_recording with:

   {
     "app_name": "Finder",
     "duration_seconds": 3
   }
   

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
start_app_window_recording	macOS app-window-bounded recording	app_name, duration_seconds
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

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.