AdAnvil

AdAnvil

An MCP server that lets an AI agent edit vertical 9:16 video ads.

AdAnvil works with Claude Code, Codex, Cursor or any MCP client. It builds ads from a brand's own footage, from a reference ad, or from an idea. The agent judges (which clips, what the text says, whether the result looks right). AdAnvil renders deterministically and checks the result: the same storyboard always gives the same video.

It is not tied to a niche. The recipes and the editing guide speak in general terms (product, benefit, problem, target customer) with examples from several niches: coffee, fashion, fitness, pets, software, home, beauty.

The demo above was made from the CC0 demo pack in examples/demo/ (four Wikimedia Commons clips, a product still and a fictional brand called Ember & Oak). No footage is stored in this repository: the pack is fetched on demand.

What it does

• Reference decoding: shots, pacing, burnt-in text and speech, plus a shot-by-shot breakdown the agent writes and compares to your edit.
• Footage library: indexing, contact sheets and mosaics so the agent can look at every clip before using it, and the speech of every video and audio file (word timestamps, searchable as soon as each file is done) so a talking creator can be cut on the pauses. Cuts are found on every frame, so the jump cuts between the takes of a long phone clip are separate shots, and the validator warns when a segment crosses one (a flash of one take, then another).
• 9 recipes (YAML) for common ad shapes: text hook, hook plus product, before and after, customer diary, comment reply, meme text, voice-over ad, long remake, talking-head UGC.
• 7 caption styles (pill, meme, outline, outline_soft, box, label, comment) with emoji support.
• Removal of burnt-in text from reference footage.
• HDR (HLG and PQ) to SDR tone-mapping.
• Music matching and loudness control.
• Optional open-source voice-over (Chatterbox) with captions synced to the spoken words, paused with start/end windows; a sentence end the voice repeats is cut and flagged.
• Talking-head UGC: best take of each line across several recordings, cuts on the pauses without hesitations, the creator's own sound kept (with B-roll laid over the voice), captions built from the speech.
• Visual devices: a before/after reveal (a divider sweeps one picture away to show the other), split screens, picture cards (a photo or a screenshot that comes in over the video), video insets (picture-in-picture), stickers and arrows, a progress bar and punch-in zooms, and information cards drawn by AdAnvil (one idea per card, one card at a time, on screen while the voice says it).
• Sound design: a pack of about 18 sound effects (CC0 or synthesised, never stored in the repository), sfx overlays and audio.sfx_auto at the cuts and captions, and cuts that snap to the beat of the music.
• End cards composed from a real product photo, and offer storyboards (story: "offer") for announcements and lead-collection ads that show the product from the first second.
• Quality control with images: automatic checks, contact sheet of the result, full-resolution frames.
• Detached background jobs for indexing, voice and rendering, so long work survives a dropped connection.

Install

Pick one path. The first is the simplest.

1. Claude Desktop extension (one click)

Download adanvil- .mcpb from the latest release, double-click it, and click Install in Claude Desktop. It asks for a projects folder and, optionally, a Freesound key (stored securely). You still need ffmpeg 6.1 or newer on your computer (brew install ffmpeg, winget install Gyan.FFmpeg, sudo apt install ffmpeg); if it is missing, the extension says so with the command for your system.

2. Docker (no Python, no ffmpeg to install)

git clone https://github.com/maxbuildog/adanvil && cd adanvil

docker build -t adanvil .

The image has ffmpeg 6.1, runs as a non-root user and speaks MCP over stdio. Mount the folder that holds your projects at /projects; the agent must give tool calls paths under /projects (for example /projects/my-ad): the image sets ADANVIL_PROJECTS_DIR=/projects, so any other folder, and /projects itself, is refused.

# Claude Code

claude mcp add adanvil -- docker run -i --rm -v "$PWD:/projects" adanvil

On Linux add --user "$(id -u):$(id -g)" so the files written to the folder belong to you.

Codex, in ~/.codex/config.toml:

[mcp_servers.adanvil]

command = "docker" args = ["run", "-i", "--rm", "-v", "/home/you/ads:/projects", "adanvil"] tool_timeout_sec = 900 default_tools_approval_mode = "approve" # needed with approval_policy = "never" (codex exec)

Cursor, in .cursor/mcp.json:

{

"mcpServers": { "adanvil": { "command": "docker", "args": ["run", "-i", "--rm", "-v", "/home/you/ads:/projects", "adanvil"] } } }

The image holds the base package only. Transcription is available with docker build --build-arg EXTRAS=transcribe -t adanvil:transcribe .. The voice, vision and music-generation environments (adanvil voice-setup, vision_setup, music-setup) are not included: they need gigabytes of models, so use the uvx path for them.

3. uvx

Requirements: Python 3.11 or newer, uv (it provides uvx), and ffmpeg 6.1 or newer, built with libzimg, on your PATH (check with ffmpeg -version; if it lives elsewhere, set ADANVIL_FFMPEG and ADANVIL_FFPROBE to the full paths).

# 1. Check the install (the first run downloads the package)

uvx --from adanvil adanvil --version

2. Register the server in Claude Code

claude mcp add adanvil -e ADANVIL_PROJECTS_DIR="$HOME/AdAnvil" -- uvx --from adanvil adanvil-mcp

3. Then ask your agent:

"Make a 9:16 ad from the footage in ./my-project"

ADANVIL_PROJECTS_DIR (recommended) is the folder that holds your projects: the server then refuses any project outside it. Projects are subfolders of it (for example ~/AdAnvil/summer-ad). See SECURITY.md.

The package is named adanvil. It installs two commands: adanvil (command line) and adanvil-mcp (the MCP server over stdio). uvx adanvil-mcp alone does not work, because uvx looks for a package with that name: always add --from.

The agent creates the project folder and tells you where to drop your files: footage in footage/, the reference ad in reference/, music in music/, logo and end card in brand/. It learns the method from the editing_guide tool and from AGENTS.md.

Codex, in ~/.codex/config.toml:

[mcp_servers.adanvil]

command = "uvx" args = ["--from", "adanvil", "adanvil-mcp"] env = { ADANVIL_PROJECTS_DIR = "/home/you/AdAnvil" } tool_timeout_sec = 900 # indexing long footage can take minutes default_tools_approval_mode = "approve" # needed with approval_policy = "never" (codex exec)

Without default_tools_approval_mode, a non-interactive codex exec run rejects every AdAnvil tool call with "MCP tool call requires approval".

Cursor, in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{

"mcpServers": { "adanvil": { "command": "uvx", "args": ["--from", "adanvil", "adanvil-mcp"], "env": { "ADANVIL_PROJECTS_DIR": "/home/you/AdAnvil" } } } }

Any other MCP client (generic stdio entry):

{

"mcpServers": { "adanvil": { "type": "stdio", "command": "uvx", "args": ["--from", "adanvil", "adanvil-mcp"], "env": { "ADANVIL_PROJECTS_DIR": "/home/you/AdAnvil" } } } }

Restart the client after editing its config, then ask the agent to call recipe_list. Nine recipes means the server is connected.

Optional: reference transcription needs the transcribe extra (faster-whisper). Use --from "adanvil[transcribe]" in place of the plain --from value above.

Try it with the demo pack

The demo needs a checkout, because the fetch script lives in the repository:

git clone https://github.com/maxbuildog/adanvil

cd adanvil uv sync uv run python examples/demo/fetch_demo.py ./demo-project uv run adanvil index ./demo-project --source footage

Then register the MCP server and ask your agent to make an ad from ./demo-project (give it the absolute path), or follow the command line walkthrough in examples/demo/README.md.

How it works

Everything lives in one project folder: footage/, brand/, music/, reference/, renders/, cache/, plus adanvil.json, brand.yaml and catalog.json. Every tool takes the absolute project_dir; every other path is relative to it and cannot escape it.

1. The agent indexes the footage, looks at the contact sheets, and optionally decodes a reference ad.
2. It picks a recipe and writes a storyboard (JSON): shots, captions, audio.
3. storyboard_validate checks the storyboard against the recipe rules, then render_start renders it in the background.
4. qc_run checks the file and returns control images that the agent looks at before delivering; ad_score scores its creative quality (aim for 80 or more).

Details: docs/ARCHITECTURE.md for the pipeline, docs/EDITING_GUIDE.md for the editing doctrine, and AGENTS.md for the step-by-step guide an agent follows (same content as skill/SKILL.md, the Claude Code skill version).

Choosing a model

The result depends on the model that drives AdAnvil. Reference analysis and shot choice are judgement work: use the strongest model you can (for example Claude Opus) for them. Smaller models execute the steps well, but they tend to copy the surface of a reference (same words, same shots) instead of rebuilding its logic for your brand.

Tools (43)

| storyboard_save | Save a storyboard as storyboards/ .json once; later tools take that