video-probe-mcp

Ask your AI assistant "is this ready for Reels?" and get a real answer.

video-probe-mcp is a Model Context Protocol server that gives Claude (or any MCP client) eyes on your video files. It reads them with ffprobe, grades them against Instagram, TikTok, YouTube, X and LinkedIn upload guidelines, and can re-encode them into upload-ready files with ffmpeg — crop, pad, or the blurred-background vertical look.

Everything runs locally. Your footage never leaves your machine.

You:    Check ~/Exports/launch_v3.mov for Reels and TikTok.
Claude: ⚠️ Two problems. It's 16:9 (1920x1080) so it'll be letterboxed, and it carries
        GPS location metadata. Everything else passes. Want me to make a 9:16 version
        with a blurred background and strip the metadata?
You:    Yes.
Claude: Done → launch_v3_instagram_reels.mp4 (1080x1920, H.264, 18 MB). Re-check: ✅ PASS

Tools

Platforms

These are practical guidelines, last reviewed November 2026. Platforms change limits often and roll them out per account and region, so length and size limits are reported as warnings, not failures. Override any field per call with custom_spec, e.g. { "max_duration_seconds": 900 }.

What gets checked

Container · video codec · pixel format / bit depth · HDR vs SDR · aspect ratio · resolution · frame rate (and VFR) · duration · file size · bitrate (too low = blocky after re-encode) · audio codec / sample rate / channels · fast start (moov atom position) · GPS location metadata.

Related MCP server: video-editor-mcp

Requirements

• Node.js 20+

• ffmpeg and ffprobe

  • macOS: brew install ffmpeg

  • Ubuntu/Debian: sudo apt install ffmpeg

  • Windows: winget install ffmpeg

The server looks for the binaries in FFMPEG_PATH / FFPROBE_PATH, then your PATH, then common install folders (/opt/homebrew/bin, /usr/local/bin, …). That last step matters: Claude Desktop on macOS launches servers with a minimal PATH that often misses Homebrew.

Install

No npm publish needed — it runs straight from GitHub with npx.

Claude Desktop

Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "video-probe": {
      "command": "npx",
      "args": ["-y", "github:anshumanofficial2002-cpu/video-probe-mcp"]
    }
  }
}

Restart Claude Desktop.

Claude Code

claude mcp add video-probe -- npx -y github:anshumanofficial2002-cpu/video-probe-mcp

Cursor / Windsurf / VS Code / other MCP clients

Use the same command in your client's MCP config:

{
  "video-probe": {
    "command": "npx",
    "args": ["-y", "github:anshumanofficial2002-cpu/video-probe-mcp"]
  }
}

From source

git clone https://github.com/anshumanofficial2002-cpu/video-probe-mcp.git
cd video-probe-mcp
npm install
npm run build
# then point your client at: node /absolute/path/to/video-probe-mcp/dist/index.js

If ffmpeg lives somewhere unusual, add it to the config:

"env": { "FFMPEG_PATH": "/path/to/ffmpeg", "FFPROBE_PATH": "/path/to/ffprobe" }

Example prompts

• "What are the specs of ~/Desktop/A001_C003.mov?"

• "Is final.mp4 ready for Instagram Reels, TikTok and YouTube Shorts?"

• "Make a 9:16 version of podcast_clip.mp4 for TikTok with blurred bars, keep the speaker on the left third."

• "Compare master.mov and export.mp4 — did anything change besides the codec?"

• "Log every clip on /Volumes/CARD_01 recursively and save the log as CSV on my Desktop."

• "Strip location metadata from vlog.mp4 before I post it." (uses conform_for_platform with strip_metadata)

• "Just give me the ffmpeg command to make this LinkedIn-ready, don't run it."

Tool reference

probe_media

check_platform_spec

conform_for_platform

HDR sources are converted to 8-bit yuv420p but not tone-mapped; the tool warns you. For accurate SDR color, tone-map in your editor first.

compare_media

paths (2–8 files), only_differences (default false).

scan_folder

probe_raw

path, stream (all | video | audio | subtitle).

Safety

• No shell. ffmpeg/ffprobe run via spawn with argument arrays, so odd file names can't inject commands.

• No surprise overwrites. Output files are refused if they exist unless you pass overwrite: true, and output can never equal input.

• Local only. No network calls, no telemetry.

• Privacy aware. GPS metadata is flagged, hidden by default, and stripped by conform_for_platform unless you opt out.

Troubleshooting

"ffmpeg/ffprobe were not found" — install ffmpeg, or set FFMPEG_PATH and FFPROBE_PATH in your client config. Run the check_setup tool to see what the server found.

Encodes are slow — use preset: "veryfast". CRF 18 at medium is the quality-first default.

Colors look flat after conforming — your source is HDR (iPhone footage often is). Export SDR from your editor, then conform.

Development

npm install
npm run build     # compile TypeScript to dist/
npm test          # unit tests + end-to-end tests over stdio (needs ffmpeg)
npm run inspect   # open the MCP Inspector against the local build

dist/ is committed so npx github:… works without a build step; CI checks it stays in sync with src/.

Related servers

Part of a small set of creator-focused MCP servers:

• video-probe-mcp — inspect and conform video for each platform

• caption-forge-mcp — SRT/VTT/ASS conversion, timing, linting and reel-style captions

• loudness-check-mcp — LUFS, true peak, normalization, silence and clipping

• frame-grab-mcp — frames, contact sheets, scene cuts and thumbnails your AI can see

• script-timer-mcp — time, trim and format scripts for short-form video

License

MIT © 2026 Anshuman