JSON2Video MCP

What is json2video-mcp-server?

json2video-mcp-server is a Model Context Protocol (MCP) server implementation designed for programmatic video generation using the json2video API. It allows users to create and manage video projects through a structured JSON schema, making it ideal for integration with Large Language Models (LLMs), automation agents, and other MCP-compatible clients.

How to use json2video-mcp-server?

json2video-mcp-server can be used by installing it via npx or npm. For npx, run env JSON2VIDEO_API_KEY=your_api_key_here npx -y @omerrgocmen/json2video-mcp. For npm, use npm install -g @omerrgocmen/json2video-mcp. Windows users might need to use cmd /c "set JSON2VIDEO_API_KEY=your_api_key_here && npx -y @omerrgocmen/json2video-mcp".

It can also be integrated with Cursor (v0.48.6+) by adding it as a new MCP server in settings, either via a command or a JSON configuration. For general MCP integration, add the server configuration to your mcp.json file, including your JSON2VIDEO_API_KEY.

Once set up, the server exposes several tools:

• generate_video: Creates a video project with customizable scenes and elements (text, image, video, audio, components, HTML, voice, audiogram, subtitles). It returns a project ID for status checking.
• get_video_status: Retrieves the status or result of a video generation job using the project ID.
• create_template: Creates a new video template.
• get_template: Retrieves details of an existing template by name.
• list_templates: Lists all available video templates.

Key Features of json2video-mcp-server

• Rich Scene and Element Support: Generate videos with diverse elements like text, images, videos, audio, components, and subtitles.
• Asynchronous Video Rendering: Supports asynchronous video generation with status polling for efficient workflow.
• Flexible JSON Schema: Utilizes a flexible and extensible JSON schema for defining video projects.
• LLM and Automation Integration: Designed for easy integration with LLMs, automation agents, and MCP-compatible tools.
• API Key Authentication: Supports API key authentication via environment variables or per-request.
• Comprehensive Error Handling and Logging: Provides robust error handling and logging for smoother operation.
• Template Management: Offers tools to create, retrieve, and list video templates.

Use Cases of json2video-mcp-server

• Automated Video Content Creation: Generate videos programmatically for marketing, social media, or educational purposes.
• Dynamic Video Personalization: Create personalized videos at scale by dynamically inserting user-specific data.
• AI-Powered Video Generation: Integrate with LLMs and AI agents to enable natural language video creation.
• Workflow Automation: Automate video production within larger automation workflows.
• Batch Video Processing: Generate multiple videos efficiently using predefined templates or dynamic data.

FAQ from json2video-mcp-server

• How do I get a JSON2VIDEO_API_KEY? You can obtain an API key from json2video.com.
• What if I encounter a client closed error? Try running npm i @omerrgocmen/json2video-mcp in your terminal.
• How do I check the status of a video generation job? Use the get_video_status tool with the project ID returned by generate_video.
• Can I customize video resolution? Yes, you can set resolution to custom and specify width and height.
• What types of elements can I include in a video? You can include text, image, video, audio, components, HTML, voice, audiogram, and subtitles.

json2video MCP Server

A Model Context Protocol (MCP) server implementation for programmatically generating videos using the json2video API. This server exposes powerful video generation and status-checking tools for use with LLMs, agents, or any MCP-compatible client.

---

Features

• Generate videos with rich scene and element support (text, image, video, audio, components, subtitles, etc.)
• Asynchronous video rendering with status polling
• Flexible, extensible JSON schema for video projects
• Designed for easy integration with LLMs, automation agents, and MCP-compatible tools
• API key authentication (env or per-request)
• Comprehensive error handling and logging

---

Installation

Running with npx

env JSON2VIDEO_API_KEY=your_api_key_here npx -y @omerrgocmen/json2video-mcp

Manual Installation

npm install -g @omerrgocmen/json2video-mcp

Windows Users

If you are on Windows and encounter issues, try:

cmd /c "set JSON2VIDEO_API_KEY=your_api_key_here && npx -y @omerrgocmen/json2video-mcp"

---

Running on Cursor

Cursor v0.48.6+

1. Open Cursor Settings
2. Go to Features > MCP Servers
3. Click "+ Add New MCP Server"
4. Enter the following:
   • Name: "json2video-mcp" (or your preferred name)
   • Type: "command"
   • Command: env JSON2VIDEO_API_KEY=your_api_key_here npx -y @omerrgocmen/json2video-mcp

Cursor v0.48.6+

1. Open Cursor Settings
2. Go to Features > MCP Servers
3. Click "+ Add new global MCP server"
4. Enter the following code:

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

Replace your_api_key_here with your json2video API key. You can get an API key from json2video.com.

After adding, refresh the MCP server list to see the new tools. Your agent or LLM will automatically use json2video MCP when appropriate, or you can explicitly request it by describing your video generation needs.

---

MCP Integration Example

Add this to your mcp.json or similar config:

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

• Replace your_api_key_here with your actual json2video API key.
• This configuration allows your agent or LLM to start and communicate with the json2video MCP server automatically.
• The server will expose the generate_video and get_video_status tools for use in your workflows.

---

Configuration

Environment Variables

• JSON2VIDEO_API_KEY (required): Your json2video API key. Can be set as an environment variable or provided per request.

---

Note: If you encounter a client closed error, run the following command in your terminal:

npm i @omerrgocmen/json2video-mcp

---

Usage

Available Tools

1. Generate Video (generate_video)

Create a customizable video project with scenes and elements.

Description: Creates a video project using the json2video API. Each project can contain multiple scenes, and each scene can contain various elements such as text, images, video, audio, components, HTML, voice, audiogram, and subtitles. Video generation is asynchronous; use the returned project ID to check status. See https://json2video.com/docs/api/ for full schema and more examples.

Input Schema:

{
  "id": "string (optional, unique identifier for the movie)",
  "comment": "string (optional, project description)",
  "cache": true,
  "client_data": {},
  "draft": true,
  "quality": "high", // one of: low, medium, high
  "resolution": "custom", // one of: sd, hd, full-hd, squared, instagram-story, instagram-feed, twitter-landscape, twitter-portrait, custom
  "width": 1920, // required if resolution is custom
  "height": 1080, // required if resolution is custom
  "variables": {},
  "elements": [ /* global elements, see below for examples */ ],
  "scenes": [
    {
      "id": "string (optional, unique scene id)",
      "comment": "string (optional)",
      "background_color": "#000000",
      "cache": true,
      "condition": "string (optional)",
      "duration": -1,
      "variables": {},
      "elements": [ /* see element examples below */ ]
    }
  ],
  "apiKey": "string (optional)"
}

Element Types & Examples:

• Text Element:

{
  "type": "text",
  "text": "Hello world",
  "duration": 5,
  "settings": { "font-size": "60px", "color": "#FF0000" }
}

• Image Element:

{
  "type": "image",
  "src": "https://images.pexels.com/photos/1105666/pexels-photo-1105666.jpeg",
  "width": 1620,
  "height": 1080,
  "x": 0,
  "y": 0
}

• Video Element:

{
  "type": "video",
  "src": "https://example.com/path/to/my/video.mp4",
  "duration": 7.3
}

• Component Element:

{
  "type": "component",
  "component": "basic/001",
  "settings": {
    "headline": { "text": "Lorem ipsum", "color": "white" },
    "body": { "text": "Dolor sit amet" }
  }
}

• HTML Element:

{
  "type": "html",
  "html": "<h1>Hello world</h1>",
  "width": 800,
  "height": 600
}

• Audio Element:

{
  "type": "audio",
  "src": "https://example.com/audio.mp3",
  "duration": 5
}

• Voice Element:

{
  "type": "voice",
  "text": "This is a voiceover.",
  "voice": "en-US-Wavenet-D"
}

• Audiogram Element:

{
  "type": "audiogram",
  "color": "#00FF00",
  "amplitude": 5
}

• Subtitles Element:

{
  "type": "subtitles",
  "captions": "1\n00:00:00,000 --> 00:00:02,000\nHello world!"
}

Example Input:

{
  "comment": "MyProject",
  "resolution": "full-hd",
  "scenes": [
    {
      "elements": [
        { "type": "video", "src": "https://example.com/path/to/my/video.mp4" },
        { "type": "text", "text": "Hello world", "duration": 5 },
        { "type": "image", "src": "https://images.pexels.com/photos/1105666/pexels-photo-1105666.jpeg", "width": 1620, "height": 1080, "x": 0, "y": 0 },
        { "type": "component", "component": "basic/001", "settings": { "headline": { "text": "Lorem ipsum" } } },
        { "type": "html", "html": "<h1>Hello world</h1>", "width": 800, "height": 600 },
        { "type": "audio", "src": "https://example.com/audio.mp3", "duration": 5 },
        { "type": "voice", "text": "This is a voiceover.", "voice": "en-US-Wavenet-D" },
        { "type": "audiogram", "color": "#00FF00", "amplitude": 5 },
        { "type": "subtitles", "captions": "1\n00:00:00,000 --> 00:00:02,000\nHello world!" }
      ]
    }
  ]
}

Notes for Users:

• Each element type has its own required and optional properties. See https://json2video.com/docs/api/ for full details.
• You can mix and match element types in scenes and globally.
• For custom resolutions, set both width and height.
• Use the returned project ID to check video status with get_video_status.

Output:

• Returns a project ID to be used with get_video_status.

2. Get Video Status (get_video_status)

Check the status or retrieve the result of a video generation job.

Description: Retrieves the status or result of a previously started video generation job. Note: Video rendering is asynchronous and may take some time. If the status is not "done", please try again later using the same project ID.

Input Schema:

{
  "project": "string (required)",
  "apiKey": "string (optional)"
}

Example Input:

{
  "project": "q663vmm2"
}

Example Output:

{
  "success": true,
  "movie": {
    "success": true,
    "status": "done",
    "message": "",
    "project": "q663vmm2",
    "url": "https://assets.json2video.com/clients/yourclient/renders/yourvideo.mp4",
    "created_at": "2025-04-27T10:44:18.880Z",
    "ended_at": "2025-04-27T10:44:28.589Z",
    "duration": 11,
    "size": 359630,
    "width": 640,
    "height": 360,
    "rendering_time": 10
  }
}

3. Create Template (create_template)

Create a new template in json2video.

Description: Creates a new template with a given name and optional description.

Input Schema:

{
  "name": "string (required, name of the template)",
  "description": "string (optional, description of the template)",
  "apiKey": "string (optional)"
}

Example Input:

{
  "name": "MyTemplate",
  "description": "A reusable video template."
}

Output:

• Returns the template ID if successful.

4. Get Template (get_template)

Get template details from json2video.

Description: Retrieves details of a template by its name.

Input Schema:

{
  "name": "string (required, name of the template)",
  "apiKey": "string (optional)"
}

Example Input:

{
  "name": "MyTemplate"
}

Output:

{
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
    "created_at": "YYYY-MM-DDTHH:MM:SSZ",
    "movie": "{\"id\":\"template1\",\"comment\":\"Example template\",\"resolution\":\"full-hd\",\"quality\":\"high\",\"scenes\":[{\"id\":\"scene1\",\"comment\":\"Scene 1\",\"elements\":[]}],\"elements\":[],\"width\":1920,\"height\":1080}",
    "name": "MyTemplate",
    "id": "MyTemplate_ID"
  }

5. List Templates (list_templates)

List all available templates from json2video.

Description: Lists all templates available to the user.

Input Schema:

{
  "apiKey": "string (optional)"
}

Example Input:

{
}

Output:

[
  {
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
    "created_at": "YYYY-MM-DDTHH:MM:SSZ",
    "movie": "{\"id\":\"template1\",\"comment\":\"Example template\",\"resolution\":\"full-hd\",\"quality\":\"high\",\"scenes\":[{\"id\":\"scene1\",\"comment\":\"Scene 1\",\"elements\":[]}],\"elements\":[],\"width\":1920,\"height\":1080}",
    "name": "MyTemplate1",
    "id": "TEMPLATE_ID_1"
  },
  {
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
    "created_at": "YYYY-MM-DDTHH:MM:SSZ",
    "movie": "{\"id\":\"template2\",\"resolution\":\"instagram-story\",\"quality\":\"medium\",\"scenes\":[{\"id\":\"scene2\",\"comment\":\"Scene 2\",\"elements\":[]}],\"elements\":[],\"comment\":\"Another template\"}",
    "name": "MyTemplate2",
    "id": "TEMPLATE_ID_2"
  }
]