# broll-mcp

> MCP server to find, preview and cut public-domain b-roll from the Internet Archive with a provenance record for every clip.

broll-mcp is an open-source MCP server, published by edigeh under the MIT license, that lets an MCP agent search the Internet Archive for public-domain footage, inspect it visually and cut short clips. Every clip is saved to disk alongside a JSON provenance record containing source, license, exact segment and attribution text.

## What It Is

broll-mcp is a Python 3.12+ stdio MCP server built around four tools: `search_footage`, `inspect_item`, `extract_clip` and `get_provenance`. An agent turns a plain-language brief into ranked archive.org results, looks at keyframe images per detected scene, and cuts a 1–60 second segment. It requires no API key and needs ffmpeg and ffprobe with HTTPS support.

## How the workflow runs

Search uses a two-stage query, first requiring every term and then matching any term, with local ranking by collection trust tier and a black-and-white preference. Results come back five per page with license and tier. Inspection runs scene detection (PySceneDetect, with ffmpeg as fallback) and returns one keyframe per scene as an MCP image so a vision model can choose a shot. For items holding many separate clips, it returns a paged clip list with thumbnails.

Cutting re-encodes to H.264 MP4 with faststart. ffprobe checks the duration is within ±0.1 s and the decode shows no errors, and three check frames are returned.

## Provenance and licensing

The provenance JSON records the source file MD5, the license copied verbatim, `commercial_use`, data node, timestamp and ready-to-paste attribution text. It is written before the clip. License labels come from an exact URL table; unrecognized URLs are marked `unrecognized` with `commercial_use: unknown`. The README notes the tool makes no legal judgement and users should check the source item before publishing.

## Archive.org etiquette and caching

The server follows archive.org's bot guidance with a descriptive User-Agent, a 1 request/second token bucket, at most four media connections, Retry-After support and exponential backoff. A SQLite WAL cache means repeated searches, inspections or cuts send no upstream requests. Settings are `BROLL_HOME`, `BROLL_AGENT_MODEL` and `BROLL_CACHE_MAX_MB`, and collection trust tiers can be edited in `tiers.toml`.

## Features
- Brief-driven two-stage search of the Internet Archive with local trust-tier ranking
- Visual inspection with one keyframe image per detected scene
- Paged clip lists with thumbnails for multi-clip items
- Verified re-encoded H.264 MP4 cuts of 1–60 seconds with check frames
- Provenance JSON record for every clip with license and attribution text
- Rate limiting and backoff following archive.org bot guidance
- SQLite WAL cache for zero-request repeats
- Structured tool outputs with stable error codes
- broll://stats resource reporting request counts and cache contents
- No API key required

## Integrations
Internet Archive, Claude Code, Claude Desktop, Cursor, MCP Inspector, ffmpeg, PySceneDetect

## Platforms
MACOS, LINUX, API, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/edigeh/broll-mcp
- Documentation: https://github.com/edigeh/broll-mcp
- Repository: https://github.com/edigeh/broll-mcp
- EveryDev.ai: https://www.everydev.ai/tools/broll-mcp