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

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.