broll-mcp

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.