Get Started in 3 Steps

Explore

Processing Parameters

Setup

The FrameFlow MCP server lets AI agents (Claude, Cursor, Windsurf, etc.) create scroll experiences programmatically. It uses the Model Context Protocol over stdio transport.

Requirements

An API key (starts with ff_live_) — generate one from API Keys.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "frameflow": {
      "command": "npx",
      "args": ["-y", "frameflow", "mcp"],
      "env": {
        "FRAMEFLOW_API_KEY": "ff_live_your_key_here"
      }
    }
  }
}

Cursor / Windsurf

Add to .cursor/mcp.json or .windsurf/mcp.json:

{
  "mcpServers": {
    "frameflow": {
      "command": "npx",
      "args": ["-y", "frameflow", "mcp"],
      "env": {
        "FRAMEFLOW_API_KEY": "ff_live_your_key_here"
      }
    }
  }
}

Upload a local video file and process it into a scroll-controlled experience. Returns the path to the downloaded ZIP export.

Create a scroll experience from a set of images using Ken Burns effects or simple sequencing.

Combine multiple video clips into a single seamless scroll experience.

Generate a video using an AI provider, then process it into a scroll experience.

List the authenticated user's past exports.

Download a specific export by its ID.

List all available presets (built-in + user-created).

No parameters required.

Check the progress and status of a processing job.

Check server health (DB connectivity, disk space, ffmpeg availability).

No parameters required.

Installation

Install FrameFlow globally or use npx:

# Install globally
npm install -g frameflow

# Or run directly with npx
npx frameflow --help

Authentication

For remote/cloud features, authenticate via browser OAuth or API key:

# Browser-based login (opens OAuth flow)
frameflow login

# Or set API key directly
export FRAMEFLOW_API_KEY=ff_live_your_key_here

# Manage API keys
frameflow api-key create --label "my-key"
frameflow api-key list
frameflow api-key revoke <id>

Credentials are stored in ~/.config/frameflow/credentials.json.

Process a local video into a scroll-controlled experience.

frameflow process hero.mp4 --fps 8 --width 1200 --format webp --export-format react

Process multiple videos at once. Accepts the same options as process.

frameflow batch clip1.mp4 clip2.mp4 clip3.mp4 --fps 12 --format webp

Quick video probe — shows duration, FPS, resolution, and estimated frame count.

frameflow preview hero.mp4

List available presets. Built-in presets: product-reveal, hero-section, tutorial, parallax-showcase.

Manage project-level defaults via .frameflowrc.

# Create a .frameflowrc in current directory
frameflow config --init

# Show current config
frameflow config --show

# Set a default
frameflow config --set fps=12
frameflow config --set format=webp

Config format (.frameflowrc):

{
  "fps": 12,
  "width": 1200,
  "height": 675,
  "format": "webp",
  "theme": "dark",
  "scrollLength": 300,
  "exportFormat": "html",
  "responsive": false,
  "adaptive": false
}

Start the FrameFlow web server with the full dashboard UI.

frameflow serve --port 5177

Remote Commands

Cloud-based processing via the FrameFlow API (requires authentication):

# Process video in the cloud
frameflow remote process hero.mp4 --fps 8 --format webp

# Generate AI video and process it
frameflow remote generate --provider runway --prompt "Cinematic product reveal"

Authentication

All API requests can be authenticated via API key or JWT token:

# API Key (recommended for automation)
curl -H "Authorization: Bearer ff_live_xxxxxxxxxxxx" \
  https://frameflow.sh/api/health

# JWT (from browser session, for web integrations)
curl -H "Authorization: Bearer eyJhbGciOi..." \
  https://frameflow.sh/api/user/profile

Upload and process a single video. Returns a job ID for progress tracking.

curl -X POST https://frameflow.sh/api/process \
  -H "Authorization: Bearer ff_live_..." \
  -F "file=@hero.mp4" \
  -F "fps=8" \
  -F "format=webp" \
  -F "exportFormat=react"

# Response: { "jobId": "abc-123-..." }

Server-Sent Events stream for real-time job progress. Connect with EventSource.

const es = new EventSource("/api/progress/abc-123");
es.onmessage = (e) => {
  const data = JSON.parse(e.data);
  // { status: "extracting", progress: 42, total: 120 }
  console.log(`${data.progress}/${data.total} frames`);
  if (data.status === "done" || data.status === "error") es.close();
};

Download the completed export ZIP for a given job ID.

curl -O -J https://frameflow.sh/api/download/abc-123 \
  -H "Authorization: Bearer ff_live_..."

Process multiple videos in one request (up to 20). Returns a batch ID.

curl -X POST https://frameflow.sh/api/batch \
  -H "Authorization: Bearer ff_live_..." \
  -F "files=@clip1.mp4" \
  -F "files=@clip2.mp4" \
  -F "fps=12" \
  -F "format=webp"

Combine up to 10 video clips (max 5 min total) into a single scroll experience.

Create a scroll experience from images (up to 50). Supports Ken Burns effects and simple sequencing.

Generate a video using an AI provider, then automatically process it into frames.

List all presets (built-in + user-created).

Create or save a custom preset.

Delete a user-created preset.

Rate Limits

Requirements

Quick Setup

# Clone the repository
git clone https://github.com/tonycdr-prog/FrameFlow.git
cd FrameFlow

# Install dependencies
npm install

# Start the server
npm start

# Or start in development mode with auto-reload
npm run dev

The server starts on http://localhost:5177 by default. No Supabase, Stripe, or external services required for local processing.

Environment Variables

All optional for basic self-hosted usage:

To enable SaaS features (auth, billing, analytics), set SUPABASE_URL and SUPABASE_SERVICE_KEY.