JSON2Video MCP Server for Programmatic Video Generation

Overview

The JSON2Video MCP Server is a lightweight Model Context Protocol (MCP) compatible backend that exposes an API for programmatic video generation. It accepts structured JSON instructions describing scenes, assets, voice-over, subtitles and other layout information, forwards those instructions to a configured video-rendering provider, and tracks rendering status until final media is available.

The server is useful when you want to integrate automated or on-demand video production into an application, agent, or LLM workflow. Instead of manual video editing, you can generate dynamic videos from templates or LLM outputs, check progress programmatically, and receive callbacks when rendering completes — making it suitable for bots, content pipelines, and automated marketing/education tooling.

Features

• Simple HTTP API for creating and tracking programmatic video jobs
• Accepts JSON “programmatic video” instructions (scenes, assets, audio, captions)
• Status and progress endpoints for polling job state
• Optional callback/webhook support for completion notifications
• Configurable provider integration (forward instructions to JSON2Video or other renderers)
• Docker-friendly, runs locally or in cloud containers
• Logging and basic configuration via environment variables

Installation / Configuration

Prerequisites: Node.js (>=14), npm or Docker.

Clone and install:

git clone https://github.com/omergocmen/json2video-mcp-server.git
cd json2video-mcp-server
npm install

Create a .env file (example):

PORT=3000
JSON2VIDEO_API_KEY=your-json2video-api-key
JSON2VIDEO_ENDPOINT=https://api.json2video.example.com/v1/render
CALLBACK_SECRET=replace-with-secret
LOG_LEVEL=info

Run locally:

# development
npm run dev

# production
npm start

Docker usage:

docker build -t json2video-mcp .
docker run -e JSON2VIDEO_API_KEY=$JSON2VIDEO_API_KEY -p 3000:3000 json2video-mcp

Configuration notes:

• JSON2VIDEO_API_KEY and JSON2VIDEO_ENDPOINT: credentials/URL for your chosen video rendering provider.
• CALLBACK_SECRET: used to validate incoming webhook callbacks if you expose a callback endpoint.

Available Resources

Common HTTP endpoints (typical names — check your local server routes after install):

• POST /mcp/videos — create a new video job
• GET /mcp/videos/:id — get job status and metadata
• POST /mcp/webhook — (optional) endpoint to receive provider callbacks
• GET /health — basic health check

Create request fields (common schema):

Status response fields:

Example POST payload (simplified):

{
  "client_id": "agent-123",
  "instructions": {
    "title": "Welcome Clip",
    "scenes": [
      {
        "type": "image",
        "src": "https://example.com/hero.jpg",
        "duration": 4
      },
      {
        "type": "text",
        "text": "Welcome to our product",
        "duration": 3
      }
    ],
    "voice": {
      "provider": "tts-provider",
      "voice": "alloy",
      "text": "Welcome to our product demo"
    },
    "subtitles": true
  },
  "callback_url": "https://app.example.com/mcp/callback",
  "metadata": { "campaign": "spring-launch" }
}

Example curl to create a job:

curl -X POST http://localhost:3000/mcp/videos \
  -H "Content-Type: application/json" \
  -d @create-payload.json

Check status:

curl http://localhost:3000/mcp/videos/<job-id>

Use Cases

• LLM-driven content generation: An LLM produces a script and scene breakdown, then calls the MCP server to render a narrated explainer video automatically.
• Agent workflows: Autonomous agents can create status updates as short videos (e.g., progress summaries, visual reports) and receive the finished URLs for sharing.
• Dynamic marketing creatives: Generate multiple personalized product demo videos from a template and customer data, then surface the results in an ad platform.
• Educational microvideos: Produce short instructional clips from structured lesson content, including captions and TTS voice-overs, ready for LMS ingestion.
• A/B testing creatives: Spawn variations of a base template with different text, voice, or images to evaluate engagement and performance.

Tips for Developers

• Start by defining a minimal instruction schema (title, scenes[], voice) and iterate as you integrate the renderer.
• Use callbacks to avoid polling — provide a callback_url to get a single POST when the job transitions to succeeded/failed.
• Keep assets (images, audio) on publicly reachable URLs so the renderer can fetch them.
• Implement idempotency for create calls if your clients may retry requests.

For implementation specifics (routes, provider adapters, and request/response formats), inspect the repository code after cloning to match the exact endpoint names and environment variables your version expects.