json2video MCP Server

json2video MCP 服务

一个 Model Context Protocol (MCP) 服务实现，用于通过 json2video API 以编程方式生成视频。该服务暴露了强大的视频生成和状态检查工具，可供大模型、Agent 或任何兼容 MCP 的客户端使用。

---

功能

• 生成支持丰富场景和元素的视频（文本、图片、视频、音频、组件、字幕等）
• 异步视频渲染，支持状态轮询
• 灵活且可扩展的视频项目 JSON schema
• 专为便于与大模型、自动化 Agent 和兼容 MCP 的工具集成而设计
• API key 身份验证（环境变量或按请求提供）
• 全面的错误处理和日志记录

---

安装

使用 npx 运行

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

手动安装

npm install -g @omerrgocmen/json2video-mcp

Windows 用户

如果你使用 Windows 并遇到问题，请尝试：

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

---

在 Cursor 上运行

Cursor v0.48.6+

1. 打开 Cursor 设置
2. 转到 Features > MCP Servers
3. 点击 "+ Add New MCP Server"
4. 输入以下内容：
   • Name: "json2video-mcp"（或你偏好的名称）
   • Type: "command"
   • Command: env JSON2VIDEO_API_KEY=your_api_key_here npx -y @omerrgocmen/json2video-mcp

Cursor v0.48.6+

1. 打开 Cursor 设置
2. 转到 Features > MCP Servers
3. 点击 "+ Add new global MCP server"
4. 输入以下代码：

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

将 your_api_key_here 替换为你的 json2video API key。你可以从 json2video.com 获取 API key。

添加后，刷新 MCP 服务列表以查看新工具。你的 Agent 或大模型会在适当时自动使用 json2video MCP，你也可以通过描述你的视频生成需求来显式请求它。

---

MCP 集成示例

将以下内容添加到你的 mcp.json 或类似配置中：

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

• 将 your_api_key_here 替换为你实际的 json2video API key。
• 此配置允许你的 Agent 或大模型自动启动 json2video MCP 服务并与之通信。
• 该服务将暴露 generate_video 和 get_video_status 工具，供你在工作流中使用。

---

配置

环境变量

• JSON2VIDEO_API_KEY（必填）：你的 json2video API key。可以设置为环境变量，也可以按请求提供。

---

注意： 如果你遇到 client closed 错误，请在终端中运行以下命令：

npm i @omerrgocmen/json2video-mcp

---

用法

可用工具

1. 生成视频（generate_video）

创建包含场景和元素的可自定义视频项目。

描述： 使用 json2video API 创建视频项目。每个项目可以包含多个场景，每个场景可以包含各种元素，例如文本、图片、视频、音频、组件、HTML、语音、音频可视化图和字幕。视频生成是异步的；使用返回的项目 ID 检查状态。有关完整 schema 和更多示例，请参阅 https://json2video.com/docs/api/。

输入 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)"
}

元素类型与示例：

• 文本元素：

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

• 图片元素：

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

• 视频元素：

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

• 组件元素：

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

• HTML 元素：

{
  "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!"
}

示例输入：

{
  "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!" }
      ]
    }
  ]
}

用户注意事项：

• 每种元素类型都有其自己的必填和可选属性。有关完整详情，请参阅 https://json2video.com/docs/api/。
• 你可以在场景中和全局范围内混合搭配元素类型。
• 如需自定义分辨率，请同时设置 width 和 height。
• 使用返回的项目 ID 通过 get_video_status 检查视频状态。

输出：

• 返回一个项目 ID，供 get_video_status 使用。

2. 获取视频状态（get_video_status）

检查视频生成任务的状态或获取其结果。

描述： 获取先前启动的视频生成任务的状态或结果。注意：视频渲染是异步的，可能需要一些时间。如果状态不是“done”，请稍后使用相同的项目 ID 重试。

输入 Schema：

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

示例输入：

{
  "project": "q663vmm2"
}

示例输出：

{
  "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）

在 json2video 中创建新模板。

描述： 使用给定名称和可选描述创建新模板。

输入 Schema：

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

示例输入：

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

输出：

• 如果成功，返回模板 ID。

4. 获取模板（get_template）

从 json2video 获取模板详情。

描述： 根据名称获取模板的详情。

输入 Schema：

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

示例输入：

{
  "name": "MyTemplate"
}

输出：

{
    "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）

列出 json2video 中所有可用的模板。

描述： 列出用户可用的所有模板。

输入 Schema：

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

示例输入：

{
}

输出：

[
  {
    "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"
  }
]