# 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](https://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](https://bgremover.online/remove-video-background/). 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:

```json
{"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**:

```json
{
  "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:

```json
{"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:

```json
{"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](docs/workflows.md) and bundled [public source provenance](vendor/provenance.json). The MIT core is a snapshot of [video-alpha-inspector](https://github.com/j-river/video-alpha-inspector), not the commercial background-removal backend. FFmpeg is a separate external dependency under its own license.

## Verify

```sh
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](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.j-river%2Fbgremover) as `io.github.j-river/bgremover`, version `0.1.0`. Public metadata links directly to [BGRemover](https://bgremover.online/) and the npm package. Source metadata is in `server.json`. MIT; no user recordings or credentials are included.