MCP server

Model Context Protocol (MCP) is an open standard for giving AI assistants secure, structured access to local tools and data sources. The @json2video/cli package ships with a built-in MCP server: once configured in your editor or agent, the model can render videos, check the status of a job, validate a movie JSON, browse templates and upload media without you having to write any glue code.

Install

npm install -g @json2video/cli

You can also skip the global install and let the editor invoke it via npx -y @json2video/cli mcp — that pattern is used in every config snippet below.

You will need a JSON2Video API key. Get one from the dashboard and either store it with json2video auth --api-key YOUR_API_KEY or pass it through the MCP config via the JSON2VIDEO_API_KEY environment variable (recommended for editor configs).

Configure your editor

Claude Code (`.mcp.json`)

Add the following to your project's .mcp.json (or the global one at ~/.claude/.mcp.json):

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

Restart Claude Code, then run /mcp to confirm the json2video server is listed as connected.

Cursor

Open Cursor settings → MCP → Add new MCP server, or edit ~/.cursor/mcp.json directly:

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

After saving, Cursor will pick up the new server automatically. You can check the connection in the MCP panel.

Windsurf

Open Windsurf settings → Cascade → MCP Servers → Edit raw config, or edit ~/.codeium/windsurf/mcp_config.json:

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

Reload the MCP servers from the Cascade panel.

Tools the MCP exposes

These are the tools your agent will see once the server is connected (source of truth: cli/src/mcp/tools.js — see cli/README.md for the authoritative list).

Tool	What it does
`render_video`	Submit a movie JSON to `POST /v2/movies` and return the project ID.
`check_status`	Poll `GET /v2/movies?project=…` and return the current status (`queued`, `running`, `done`, `error`).
`validate_movie`	Validate a movie JSON locally against the schema before submitting.
`list_templates`	List the templates available in the current account.
`list_featured_templates`	List templates from the public library, optionally filtered by tag.
`get_template`	Fetch a template's variables (as JSON Schema) and optionally its full movie source.
`get_example`	Return a named example movie JSON the agent can use as a starting point.
`get_help`	Pull a documentation snippet from the docs so the agent can self-serve without leaving the editor.
`get_account`	Return the current account info (plan, credits remaining, etc.).
`media_list`	List files in a folder of your account's media library.
`media_get`	Download a single file from media.
`media_upload`	Upload a local file (or URL) to media.
`media_delete`	Delete a file from media.

The MCP server uses stdio transport. You can also run it manually for debugging with json2video mcp — it will wait for an MCP client to connect on stdin/stdout.

Troubleshooting

Authentication errors — the most common failure mode is a missing or wrong API key. Check that:

JSON2VIDEO_API_KEY is set in the env block of your MCP config, or
json2video auth --api-key YOUR_API_KEY has been run on the machine where the MCP server starts (key stored at ~/.config/json2video/config.json).

A 401 / 403 from any tool almost always means the key is missing, expired, or restricted to a different environment.

Network errors — @json2video/cli talks to https://api.json2video.com. If you're behind a corporate firewall or a proxy:

Allow outbound HTTPS to api.json2video.com and cdn.json2video.com.
Export HTTPS_PROXY (and HTTP_PROXY if you proxy plain HTTP) in the environment where the MCP server starts.

npx -y @json2video/cli keeps re-downloading — the -y flag accepts the install prompt every time but it's still cached after the first run. If your editor reports a slow startup, install globally with npm install -g @json2video/cli and change the command in your config to json2video and the args to ["mcp"].

Common errors

Project not found — the project ID is wrong or belongs to another account / API key.
Invalid movie from validate_movie — the JSON does not match the schema. The error message includes the offending path; fix it and re-validate. See the Rules for your agent page for the conventions that prevent most validation failures.
Your account doesn't have enough credits for this render… / Your account is out of credits… (account_suspended) / You exceeded the quota … — the account is out of credits or has hit a plan limit. Do not retry; upgrade the plan or buy credits at https://json2video.com/dashboard/credits. See Rate limits & quotas.
Your default ElevenLabs key (connection "…") failed: … or Voice "…" was not found in your ElevenLabs account — the render ran on the user's own ElevenLabs key (their default key in Dashboard → Connections, or connection). The MCP server cannot manage connections: fix the key in the dashboard, change the voice, or set "connection": "none" on the voice to use JSON2Video's key. See the voice element's connection.

If something else is going wrong, run json2video mcp directly from a terminal — the same process the editor spawns. Errors and stack traces print to stderr, which is otherwise swallowed by the MCP client.

MCP server#

Install#

Configure your editor#

Claude Code (.mcp.json)#

Cursor#

Windsurf#

Tools the MCP exposes#

Troubleshooting#