BGRemover MCP — Video Transparency & Alpha Inspection

Inspect decoded alpha samples from trusted local videos and analyze supplied alpha-channel bytes from a local MCP client. An open-source companion to BGRemover Online.

This MCP checks transparency; it does not remove backgrounds or convert media. For the separate product's processing workflow, see video background removal. No paid credits, account or API key are used by this MCP.

Install

Requires Node.js 22+. Pixel analysis works without FFmpeg. Video inspection requires separately installed FFmpeg and ffprobe, including libvpx VP8/VP9 decoders. The package does not download or install binaries.

Common local stdio client configuration, with file reads disabled:

{"mcpServers":{"bgremover":{"command":"npx","args":["-y","bgremover-mcp@0.1.0"]}}}

For video inspection, explicitly opt in to one existing media directory in your trusted client configuration:

{
  "mcpServers": {
    "bgremover": {
      "command": "npx",
      "args": ["-y", "bgremover-mcp@0.1.0"],
      "env": {"BGREMOVER_MEDIA_ROOT": "/absolute/path/to/your/media"}
    }
  }
}

Choose a dedicated directory of media you intend to inspect, not your home directory. On Windows, use your actual folder with JSON-escaped backslashes or forward slashes. If a client cannot start npx, install the package and launch its absolute src/cli.js path using node.

BGREMOVER_FFMPEG and BGREMOVER_FFPROBE can specify trusted executable paths at launch. Tool callers cannot choose executables or change the media root.

Two tools

Tool	Input	Result
analyze_alpha_plane	Canonical Base64 8-bit alpha bytes, width, height, optional thresholds	Pixel counts, mean/range, transparency/visibility fractions
inspect_video_alpha	relativePath within configured media root, optional sampleFractions and thresholds	Decoded sample statistics, video facts and a bounded sampling conclusion

Exact pixel example:

{"alphaBase64":"AID//w==","width":2,"height":2}

Those bytes are [0, 128, 255, 255]: one zero-alpha pixel, one partial pixel and two fully opaque pixels. The mean is 159.5. No video has been decoded by the pixel tool.

For a video inside your authorized directory:

{"relativePath":"cutout.webm","sampleFractions":[0,0.25,0.5,0.75]}

Ask your agent:

Inspect cutout.webm in the configured media directory. Distinguish the container's alpha metadata from actual decoded samples. Do not conclude the entire video is opaque from a few negative samples.

What the result means

• transparency-detected: sampled frames have significant transparency and visibility under the selected thresholds.
• fully-transparent-samples: sampled alpha pixels are all zero, not necessarily a useful visible cutout.
• no-transparency-observed: no sampled pixel crosses the transparency threshold; this is not a full-video proof.
• inconclusive: some transparency exists but the significance criteria do not support a stronger conclusion.

alphaMetadata alone is not proof. A VP9 WebM can advertise alpha while all decoded alpha pixels are 255. The test suite generates both a true cutout and this misleading opaque case.

Limits and trust boundary

• Pixel analysis: at most 65,536 pixels. One byte per pixel, exact width × height, canonical padded Base64.
• Video inspection: at most 64 MiB, 120 seconds, 30 seconds processing, 8 sample positions and 256-pixel sampled long edge; one inspection at a time per server.
• Container inputs are restricted to recognized WebM/MKV/MOV/MP4 headers and extensions; codecs VP8, VP9, ProRes and H.264. No HEVC-alpha support, playlists or URL inputs.
• Absolute paths, traversal and resolved symlink escapes are rejected. This is a path guard, not an OS sandbox for native FFmpeg. Inspect trusted, stable files and keep FFmpeg updated. Do not allow another process to swap files while inspection is running.
• FFmpeg is launched without a shell and with a file-only protocol allowlist. Original files are not modified. Results do not return full paths, source media, metadata tags or raw frames.
• The server does not upload video or contact a paid API. Your AI client/model provider may transmit relative filenames and tool results. Local processing does not make the whole AI workflow offline.

See alpha inspection workflows and bundled public source provenance. The MIT core is a snapshot of video-alpha-inspector, not the commercial background-removal backend. FFmpeg is a separate external dependency under its own license.

Verify

npm ci --ignore-scripts
npm run check
npm run audit:public
npm pack --dry-run

Tests use real MCP stdio calls and synthetic FFmpeg-generated videos. FFmpeg is required for tests; media checks are not silently skipped. Coverage includes transparent/opaque samples, metadata ambiguity, default-disabled reads, path traversal, symlink escape, input limits and executable-argument rejection.

Published in the official MCP Registry as io.github.j-river/bgremover, version 0.1.0. Public metadata links directly to BGRemover and the npm package. Source metadata is in server.json. MIT; no user recordings or credentials are included.