JSON2Video CLI

Command-line tool and MCP server for creating videos programmatically using the JSON2Video API.

What it does

• Render videos from JSON definitions via the command line
• Validate movie JSON locally before submitting
• Check status of rendering jobs
• Manage media — upload, list, download and delete files
• Browse templates and examples
• MCP server for AI agent integration (Claude Code, Cursor, etc.)

Requirements

• Node.js >= 20.0.0
• A JSON2Video API key (get one here)

Installation

Via npm (recommended)

npm install -g @json2video/cli

Via npx (no install)

npx @json2video/cli render movie.json

Setup

Authenticate with your API key:

json2video auth --api-key YOUR_API_KEY

Or set it as an environment variable:

export JSON2VIDEO_API_KEY=YOUR_API_KEY

The API key is stored in ~/.config/json2video/config.json.

Usage

Render a video

json2video render movie.json
json2video render movie.json --wait        # Wait for the render to finish
json2video render movie.json --wait --json  # JSON output
cat movie.json | json2video render --stdin  # From stdin

Check render status

json2video status PROJECT_ID
json2video status PROJECT_ID --wait  # Poll until done

Validate movie JSON

json2video validate movie.json

Browse templates

json2video templates                    # List your templates
json2video templates-library            # List featured templates from the library
json2video templates-library --tag TAG  # Filter featured templates by tag
json2video template TEMPLATE_ID         # Template info + variables (JSON Schema)
json2video template TEMPLATE_ID --code  # Full movie JSON source code

View examples

json2video examples        # List available examples
json2video examples basic  # Show a specific example

Media files

json2video media upload photo.jpg                # Upload to root folder
json2video media upload photo.jpg --folder avatars  # Upload to a specific folder
json2video media list                            # List files in root
json2video media list /avatars                   # List files in a folder
json2video media get /avatars/photo.jpg          # Download a file
json2video media get /avatars/photo.jpg -o p.jpg # Download with custom filename
json2video media delete /avatars/photo.jpg       # Delete a file

Account info

json2video account

JSON syntax reference

json2video docs movie
json2video docs elements
json2video docs text
json2video docs transitions

MCP Server

The CLI includes a built-in MCP (Model Context Protocol) server for AI agent integration.

Configure in Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "json2video": {
      "command": "npx",
      "args": ["-y", "@json2video/cli", "mcp"],
      "env": {
        "JSON2VIDEO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Start manually

json2video mcp

The MCP server uses stdio transport and exposes tools for rendering videos, checking status, validating JSON, browsing templates, and querying help.

Development

Project structure

cli/
├── bin/json2video.js    # Dev entrypoint (with shebang)
├── src/
│   ├── cli.js           # CLI setup (commander)
│   ├── cli-entry.js     # Build entrypoint (without shebang)
│   ├── commands/        # CLI commands (auth, render, status, etc.)
│   ├── lib/             # Shared utilities (api-client, config, etc.)
│   └── mcp/             # MCP server and tool definitions
├── build.mjs            # esbuild bundler script
├── dist/                # Built output (git-ignored)
│   └── json2video.cjs   # Bundled single-file CLI
└── package.json

Run in development

cd cli
npm install
node bin/json2video.js --help

Build

Two build modes:

npm run build              # For npm publish (dependencies stay external, ~90KB)
npm run build:standalone   # Self-contained single file (all deps bundled, ~1.2MB)

The build uses esbuild to bundle all source files into a single dist/json2video.cjs with a shebang header.

Publish to npm

npm run build
npm publish --access public

The prepublishOnly script runs the build automatically, so npm publish alone is sufficient.

Only the dist/ directory is included in the published package (configured via the files field in package.json).

Environment variables

License

MIT