⚡ FrameForge

AI Video Production Engine for Any Agentic IDE

Any IDE. Any topic. Any style. 1080p videos from a single prompt.

FrameForge is an MCP server your IDE agent calls to make videos. You (or your agent) write the scenes — FrameForge handles voice, images, FFmpeg compositing, and quality checking. Works in Bob, Cursor, Windsurf, Codex, opencode, Claude Code, and any MCP-capable IDE.

Zero-install quickstart (npx)

No cloning. No npm install. FFmpeg and edge-tts run on your own machine.

# 1. Install prerequisites (one-time, system-level)
#    FFmpeg: https://ffmpeg.org/download.html  →  add bin/ to PATH
#    edge-tts: pip install edge-tts

# 2. Configure your API keys (one-time, saved to ~/.frameforge/config.json)
npx --package=@amg555/frameforge-mcp frameforge-setup

# 3. Check everything is ready
npx --package=@amg555/frameforge-mcp frameforge-doctor

# 4. Add to your IDE — then ask your agent to make a video

Add to your IDE's MCP config (works in Bob, Cursor, Windsurf, Codex, Claude Code, opencode):

{
  "mcpServers": {
    "frameforge": {
      "command": "npx",
      "args": ["--package=@amg555/frameforge-mcp", "-y", "frameforge-mcp"]
    }
  }
}

That's it. Your agent now has 19 video production & autonomous editing tools. FFmpeg and TTS run on your machine — no cloud render costs.

Related MCP server: short-video-maker

Other connection methods

Cloned repo (contributors / local dev)

git clone https://github.com/AMG555/FrameForge.git && cd FrameForge && npm run doctor && npm run setup

{
  "mcpServers": {
    "frameforge": {
      "command": "node",
      "args": ["/absolute/path/to/FrameForge/src/mcp-server/stdio.js"]
    }
  }
}

Remote URL (Cloudflare Workers — FFmpeg must run separately)

Deploy once to Cloudflare (free):

cd cloudflare-mcp && npm install
wrangler secret put WORKER_API_URL   # your FrameForge backend URL
wrangler secret put MCP_AUTH_TOKEN   # any random 32-char string
wrangler deploy

{
  "mcpServers": {
    "frameforge": {
      "url": "https://video-mcp.YOUR_SUBDOMAIN.workers.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN" }
    }
  }
}

Make your first video

New to FrameForge? Read START_HERE.md — it's a single file you paste into any IDE chat that starts a guided conversation: the agent asks what you want to make, produces a beat sheet for your approval, then drives the full pipeline.

Once connected, tell your IDE:

"Make a 60-second explainer video about how GPS works"

Or call the tool directly:

create_video_from_script({
  scenes: [
    {
      narration: "GPS works by triangulating signals from at least four satellites.",
      caption: "GPS TRIANGULATION",
      visual_description: "satellite orbiting earth, flat illustration, bold colors"
    },
    {
      narration: "Your phone measures tiny timing differences to pinpoint your location.",
      caption: "YOUR LOCATION",
      visual_description: "phone with pin on map, white background, minimal"
    }
  ],
  title: "How GPS Works"
})

Output lands in .frameforge-files/:

final_video_<id>.mp4   →  1080p landscape master
short_1_<id>.mp4       →  auto-extracted 9:16 vertical Short
video_meta.json        →  title, description, tags, chapters

No API keys required for this path. edge-tts (voice) runs offline and visual cards render procedurally via FFmpeg/Playwright. 100% deterministic, zero diffusion flaws.

Two ways to use it

Your IDE writes the script — no LLM key needed

Your IDE's model writes the scenes. FrameForge runs FFmpeg, TTS, and code-driven kinetic animations or user media. Use create_video_from_script. This is the fastest path and what most people want.

FrameForge researches and scripts itself

For batch runs or when running without an IDE. Requires a free LLM key (Groq or Gemini both have free tiers).

npm run make -- --topic "How does GPS actually work?"

Bring your own media

Skip AI generation for any scene by supplying your own files:

{
  "narration": "Here is the sorting algorithm running step by step.",
  "caption": "ALGORITHM",
  "video_path": "/recordings/screen_capture.mp4",
  "audio_path": "/recordings/my_voice.mp3"
}

Any combination of image_path, video_path, audio_path works — FrameForge only generates what you don't supply.

Tools

19 tools, grouped by what you're doing:

Make a video from your own script (no LLM key)

Auto-research pipeline (needs a free LLM key)

Code-driven animated video (Playwright + FFmpeg)

Providers

Switch any provider with one .env change — no code changes.

Voice (TTS)

Set PROVIDER_TTS=<name>.

Visuals & Media

FrameForge is code-driven first: scenes render via crisp vector animations, kinetic typography, and user-provided media (clips, b-roll, photos) — zero diffusion artifacts, zero AI slop, 100% deterministic.

Set ENABLE_AI_IMAGES=true or pass --ai-images only if you explicitly want AI diffusion images. Default is clean code-driven animation.

LLM — only for the auto-research path

Skip entirely when using create_video_from_script.

Set PROVIDER_LLM=<name>.

Quality gates

Every video passes 7 checks before delivery. Any failure blocks the output.

CLI commands

Via npx (no clone needed):

Via cloned repo:

Architecture

YOUR IDE (Bob / Codex / opencode / Cursor / Windsurf / Claude Code)
         │
         │  HTTPS + SSE  (Cloudflare Remote MCP — optional)
         ▼
[Cloudflare Worker]     proxies tool calls, keeps IDE context lean
         │
         │  HTTP + INTERNAL_API_TOKEN
         ▼
[FrameForge Node]       runs on VPS / Pi / your machine / Render.com
         │
         ├─ src/mcp-server/     17 MCP tools
         ├─ src/workflows/      research → script → assets → render → publish
         ├─ src/pipeline/       state machine, retry, telemetry, manifest
         ├─ src/video-renderer/ FFmpeg scene render + concat
         ├─ src/audio-mixer/    LUFS normalise, sidechain ducking
         └─ src/quality-gate/   7-point output validation

Security

• Timing-safe auth — all token comparisons use crypto.timingSafeEqual

• SSRF protection — webhook and pipeline URLs validated against RFC-1918 / loopback / link-local blocklist

• Path traversal guards — productionId, audioPath, localPath validated before any file I/O

• CLI injection guards — animation timestamps allowlisted before passing to render.mjs

• Worker API auth — INTERNAL_API_TOKEN Bearer check on all internal routes

• Body size limits — all HTTP servers reject requests > 4 MB with HTTP 413

• Credential redaction — 14+ regex patterns strip API keys from all logs

Report vulnerabilities: SECURITY.md

Deployment

npx (no install — recommended for users):

npx --package=@amg555/frameforge-mcp frameforge-setup
# then add the IDE config from the quickstart above

VPS / Pi / self-hosted (cloned repo):

git clone https://github.com/AMG555/FrameForge.git && cd FrameForge
cp docs/env.template .env   # edit with your keys
npm run mcp

See docs/deployment.md for Docker, systemd, and Render.com setup.

Testing

npm test          # 512 tests, 0 failures
npm run validate  # 113 structural checks

Contributing

See CONTRIBUTING.md.

1. npm run doctor passes on your OS

2. npm test passes (512/512)

3. npm run validate passes (113/113)

4. FFmpeg commands keep -nostdin and cross-platform font paths

License

MIT — see LICENSE.