Video Assets Server MCP server for AI agents

Video Assets Server is a Model Context Protocol server. Connect it once and your agent can search every video source, check licences, pick the right rendition and cut b-roll sequences while it works on your video, site or app.

MCP endpoint: https://video.shep.bot/mcp (Streamable HTTP, no authentication). Register it under the name video.

Claude Code

claude mcp add --transport http video https://video.shep.bot/mcp

Add --scope user to make it available in every project, or --scope project to share it with your team through .mcp.json. Check it with claude mcp list, or /mcp inside a session.

Cursor

Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project (the home page has a one-click “Add to Cursor” button):

{
  "mcpServers": {
    "video": { "url": "https://video.shep.bot/mcp" }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json, then use Copilot Chat in Agent mode:

{
  "servers": {
    "video": { "type": "http", "url": "https://video.shep.bot/mcp" }
  }
}

Or from a terminal: code --add-mcp '{"name":"video","type":"http","url":"https://video.shep.bot/mcp"}'

Claude desktop app and claude.ai

Open Settings → Connectors → Add custom connector, name it Video Assets Server and paste https://video.shep.bot/mcp.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "video": { "serverUrl": "https://video.shep.bot/mcp" }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.video]
url = "https://video.shep.bot/mcp"

Gemini CLI

gemini mcp add --transport http video https://video.shep.bot/mcp

Any other client

Clients that only support stdio servers can bridge to the HTTP endpoint with mcp-remote:

{
  "mcpServers": {
    "video": { "command": "npx", "args": ["-y", "mcp-remote", "https://video.shep.bot/mcp"] }
  }
}

Tools your agent gets

Tool	What it does
search_videos	Search every source. Arguments: query (editor words work: “ocean waves at sunset”, “4k vertical drone city 10s”, “timelapse city night 60fps”), categories (e.g. nature.ocean, aerial, space.launch, background.abstract, archive.newsreel), styles (timelapse, slow-motion, loop, animation, visualization, black-white), orientation, min_resolution (720, 1080, 1440, 2160), min_duration, max_duration, min_fps, has_audio, commercial_only (default true), free_only, downloadable_only, strict, providers, limit, offset. Also returns also_search_on: deep links into the stock sites that can’t be searched automatically.
get_video	Details for one id: licence, verdict, editorial flag and credit line, every rendition (size, container, codec), a watch URL that plays in a browser straight from the source, and selection.downloadUrl for the file closest to height (and format).
build_sequence	Turns a shot list (a list, or text with one shot per line and “(3s)” lengths) into a b-roll sequence: one clip per shot matching orientation (or width/height), fps and total_duration, commercial-safe by default, with alternatives, plus timeline.otio, an ffmpeg concat.sh, a Remotion clip list and ATTRIBUTION.md.
list_sources	Every source with what it is best for, categories, pricing, licence and whether it is searched or linked.
download_video	Local servers only: writes the chosen rendition into ./footage/<category>/ and keeps ATTRIBUTION.md and credits.json up to date.

The hosted server never writes to its own disk, so agents with a shell download through the links it returns (the download URL redirects to the file on the source):

mkdir -p footage
curl -L -o footage/launch.mp4 "https://video.shep.bot/v1/clips/<id>/download?height=1080"

Licence rules the agent follows

Stock footage licences have traps, so the server tells every agent the same rules, and you can expect them to be followed:

• Searches are commercial-safe by default (commercial_only=true). The agent turns that off only when you say the project is personal, educational or non-commercial.
• It reports the verdict of every clip it suggests, and never presents a no (non-commercial), check-terms (unclear) or editorial clip as cleared for advertising.
• license.editorial: true means people, insignia or brands appear without releases: fine for news, documentary and education, not for ads or anything that implies endorsement. All NASA footage carries it.
• When a clip needs credit (yes-with-credit), it gives you the exact attribution line; local downloads and sequences collect them in ATTRIBUTION.md.
• Uploader-asserted licences (most of the Internet Archive) are flagged as unverified.

Details: Video licences explained.

Prompts that work well

Find three 4K clips of ocean waves at sunset for a client ad. Commercial-safe only, no editorial clips. Show me each one's licence and credit line first.

Build a 30-second vertical b-roll sequence for an Instagram Reel: city skyline at night (4s), coffee pour close-up (3s), people walking in the rain, clouds timelapse. Give me the ffmpeg script and ATTRIBUTION.md.

I'm making a documentary about the space race. Find 1960s rocket launch footage and archive newsreels, and tell me which ones are public domain.

Tips for agents and the people prompting them:

• Describe the shot, not the file: “drone shot over a forest at sunrise”, “slow motion rocket engine”, “abstract particles loop”.
• Put the format in the words or the filters: “vertical”, “4k”, “at least 10 seconds”, “60fps”.
• Results with downloadable: false must be fetched from their url on the source site. Internet Archive results have no preview until get_video reads their file list.

Local mode: downloads straight to disk

For download_video and sequence downloads into your project, run the server locally over stdio:

claude mcp add video-local -- npx -y video-assets-server mcp

Or with Docker, mounting your footage folder:

claude mcp add video-local -- docker run -i --rm \
  --user "$(id -u):$(id -g)" -v "$PWD/footage:/app/footage" \
  ghcr.io/arielshad/video-assets-server node dist/cli.js mcp

Files land in ./footage/<category>/ (set VIDEO_DOWNLOAD_DIR to change it), with ATTRIBUTION.md and credits.json next to them. build_sequence with download=true saves the picks into ./footage/sequences/<name>/footage/ and writes the exports next to them, pointing at the local files. No source needs an API key.

Agents without MCP

Any agent that can fetch URLs can use the REST API directly. Point it at /AGENTS.md; it has the whole workflow and the licence rules in a few lines. In Claude Code you can also install the ready-made skill:

mkdir -p ~/.claude/skills/video
curl -fsSL https://video.shep.bot/skill/SKILL.md -o ~/.claude/skills/video/SKILL.md