# video-face-masking-mcp

Automatically detect and mask people in video and images — and undo it later.
Unlike one-way anonymization, masking here is **reversible**: original regions are encrypted
with a key you keep, so restoration of the original footage is possible for legal review or audit.

영상·이미지 속 얼굴을 자동으로 탐지해 모자이크 처리하는 MCP 서버입니다.
프레임마다 손으로 가릴 필요가 없고, 발급된 키로 원본 복원이 가능합니다.

---

## What this solves

Masking faces in a video by hand does not scale. A 12-minute clip at 30fps is over 21,000
frames. Picking coordinates for every person in every frame is not realistic work.

This server takes a different approach: detection is automatic. You do not select coordinates.
The server finds faces in each frame and masks only those regions — never the whole frame.

## Use this when

- A video or photo contains **bystanders** whose faces must be hidden before publishing
- A clip is **too long to mask frame by frame by hand**
- **Several people** appear at once and each of them must be masked
- You need to **restore the original later** — for legal review or internal audit
- You want **mosaic, blur, or solid redaction** rather than a full-image filter

## What it does

| Capability | Detail |
|---|---|
| Automatic face detection | No coordinates required. Multiple faces per frame. |
| Masking styles | mosaic (pixelation), gaussian blur, solid redaction |
| Targets | face (body and license plate planned) |
| Media | image, video |
| **Reversible masking** | Original regions are encrypted with a key you keep. Restore with that key. |
| Long media | Processed as a job you can poll, then download the result |

### Reversible masking

Most anonymization is one-way. This server encrypts the original pixel regions before masking
them and returns a key. Passing that key to the restore tool puts the original back.

Restoration is pixel-exact for images (output is written as lossless PNG). For video, frames are
re-encoded, so restoration is visually faithful but not bit-identical.

The key is returned to the caller and not stored server-side. If the key is lost, the masking
is permanent.

### What this is not

This hides people by covering the detected regions. It does not erase them or repaint the
background — it is not video inpainting or object removal. If you need the background
reconstructed behind a person, this is not the right tool.

## Tools

| Tool | Purpose |
|---|---|
| `mask_image` | Detect and mask faces in an image in a single call |
| `mask_video` | Detect and mask faces across video frames in a single call |
| `restore_media` | Restore a masked result to the original using the key |
| `get_job_status` | Poll a running job |
| `get_masking_options` | Describe supported targets, styles, and limits |

## Quick start

```bash
docker build -t video-face-masking-mcp .
docker run --rm -p 8765:8765 video-face-masking-mcp
```

The MCP endpoint is served over Streamable HTTP at `/mcp`.
A server card is published at `/.well-known/mcp/server-card.json`.

## Also known as

video mosaic, video face blur, automatic face masking, face redaction, video de-identification,
video anonymization, privacy masking, batch face detection masking, reversible masking,
restoration of masked video, hiding people in video

## 한국어 안내

- 영상에서 지나가는 행인 얼굴을 자동으로 찾아 모자이크 처리합니다
- 좌표를 일일이 지정하지 않아도 됩니다
- 여러 명이 동시에 나와도 한 번에 처리됩니다
- 법적 확인 등을 위해 원본 복원이 필요한 경우, 발급된 키로 되돌릴 수 있습니다
- 전체 화면을 흐리게 하는 방식이 아니라, 탐지된 얼굴 영역만 처리합니다

## License

MIT