MCP server

Model Context Protocol (MCP) is an open standard for giving AI assistants secure, structured access to tools and data sources. JSON2Video offers two MCP servers, with the same tools:

Remote MCP server — paste one URL into Claude, ChatGPT, Claude Code, Cursor or VS Code, sign in with your JSON2Video account, and the assistant can make videos for you. Nothing to install, no API key to copy. This is the easiest option, and the only one that works in claude.ai and ChatGPT.
Local MCP server — the @json2video/cli package runs on your computer and talks to your editor over stdio. Use it for offline work, CI, and editors that only support local servers (Windsurf, for example).

Either way, the model can render videos, check the status of a job, validate a movie JSON, browse and save templates and upload media without you writing any glue code.

Remote MCP server (connect by URL)

The remote server lives at:

https://mcp.json2video.com/mcp

Add that URL to your AI app as a custom MCP server (called a connector in Claude and ChatGPT). The first time you use it, the app sends you to JSON2Video to sign in and approve the connection. After that you can ask for videos in plain language, for example "Make a 30-second vertical video that announces our spring sale, using these three product photos".

Videos are rendered with the credits of the JSON2Video account you sign in with, exactly as if you had made them from the dashboard or the API.

Before you start

You need a JSON2Video account. The free plan and every paid plan can connect apps. (Very old free accounts that cannot create API keys cannot connect; see Troubleshooting.)
You do not need to create or paste an API key. The connection creates its own key for you (see Connected apps).
Use the URL exactly as shown, including /mcp at the end.

Connect from claude.ai and Claude Desktop

Open Settings → Connectors (in some versions, Customize → Connectors).
Click Add custom connector.
Enter the name JSON2Video and the URL https://mcp.json2video.com/mcp, then click Add.
Click Connect next to the new connector and sign in to JSON2Video when asked.
Approve the connection on the consent page.
In a chat, turn the JSON2Video connector on from the tools menu and ask for a video.

On Claude Team and Enterprise plans, an organization owner adds the connector once in the organization's connector settings. Each member then clicks Connect and signs in with their own JSON2Video account, so every person renders with their own credits.

Claude Desktop uses the same connectors list as claude.ai; remote servers are added there, not in claude_desktop_config.json.

Connect from ChatGPT

Open Settings → Connectors and click Add, then choose Add custom MCP server.
Enter the name JSON2Video and the URL https://mcp.json2video.com/mcp.
Choose OAuth as the authentication method, then continue.
Sign in to JSON2Video and approve the connection on the consent page.
In a new chat, add the JSON2Video connector and ask for a video.

Custom MCP servers are not available on every ChatGPT plan, and in workspaces (Business, Enterprise, Edu) an admin may need to enable them first. If you do not see Add custom MCP server, check your plan and workspace settings in ChatGPT.

Connect from Claude Code

Add the server, then sign in:

claude mcp add --transport http json2video https://mcp.json2video.com/mcp

Open Claude Code, run /mcp, select json2video and choose Authenticate. Your browser opens the JSON2Video consent page. Once approved, /mcp shows the server as connected.

To share the server with everyone who works on a project, add --scope project: it is saved in the project's .mcp.json, and each person signs in with their own account.

Connect from Cursor

Add the server to ~/.cursor/mcp.json (or the project's .cursor/mcp.json):

{
  "mcpServers": {
    "json2video": {
      "url": "https://mcp.json2video.com/mcp"
    }
  }
}

Cursor opens the JSON2Video sign-in the first time the server is used. If the server shows as needing sign-in in Settings → MCP, use the connect button next to it.

Connect from VS Code

Add the server to .vscode/mcp.json in your workspace (or run MCP: Add Server from the command palette and choose HTTP):

{
  "servers": {
    "json2video": {
      "type": "http",
      "url": "https://mcp.json2video.com/mcp"
    }
  }
}

VS Code asks you to sign in the first time the server is used. You can also start or restart the server from the MCP: List Servers command.

Sign in and consent

When you connect, your browser opens JSON2Video. If you are not signed in, sign in first (email, magic link or Google, like in the dashboard). Then you see the consent page:

<App> wants to connect to your JSON2Video account It will be able to: render videos with your credits, read and save your templates, manage your media files and read your account details. Allow / Cancel

The page shows the name of the app that is asking and the address it will return to, so you can check you started the connection yourself.
Signed in with the wrong account? Use the Use another account link on the page.
Allow completes the connection and takes you back to the app. Cancel stops it; nothing is created.
Your password is never shared with the app. It only receives a token that works with the JSON2Video MCP server.

Connected apps and revoking access

Each app you allow gets its own API key in your account, named <App> (connected app) (for example Claude (connected app)). You can see it in Dashboard → API Keys. Renders made through the app are counted against your account like any other render.

To see what is connected, open Dashboard → Account and look for Connected apps. It lists every app with the date it was connected and when it was last used.

To disconnect an app, click Revoke next to it. This removes the app's access and deletes its API key. The next time the app tries to use JSON2Video it is told to sign in again, and you can approve it again whenever you want. Deleting the (connected app) key from the API Keys page has the same effect.

Videos that were already rendering when you revoke access are not cancelled.

An account can have up to 20 API keys in total. Connected apps count toward that limit.

Use an API key instead

If you cannot sign in through a browser (a server, CI, a script, or an automation tool with an MCP client node), send an API key with each request. Both headers work:

Authorization: Bearer YOUR_API_KEY
x-api-key: YOUR_API_KEY

For example, in Claude Code:

claude mcp add --transport http json2video https://mcp.json2video.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Create the key in Dashboard → API Keys. Use the lowest role that does the job: Render is enough to render videos, Editor adds saving templates, and Manager is what connected apps use. See API keys.

Limits and behavior

Renders return a project ID right away. render_video waits about 20 seconds. If the video is not ready by then, the assistant gets the project ID and checks progress with check_status. Long videos keep rendering in the background. If the conversation is interrupted, ask the assistant to run list_recent_renders to find the video again.
media_upload accepts public URLs only, up to 50 MB per file. The remote server cannot read files from your computer. To use your own files, upload them in Dashboard → Media and give the assistant the resulting URL, or use the local server.
Tools and credits are the same as the local server (see Tools the MCP exposes). Credit use and plan limits are explained in Rate limits & quotas.
Sessions last a long time. The app stays connected for as long as you keep using it (it refreshes its access automatically). If it is unused for about two months, you will be asked to sign in again.

Troubleshooting the remote server

"Key limit reached" on the consent page — your account already has 20 API keys, and a connected app needs one. Open Dashboard → API Keys, delete keys you no longer use (including (connected app) keys of apps you stopped using), and click Try again on the consent page.

"Your current plan cannot connect apps" — only accounts that can create API keys can connect apps. The free plan and all current paid plans can. Very old legacy free accounts cannot; choose a plan at json2video.com/pricing and connect again.

"Unknown application" — the consent link is old or was opened without the app that started it. Go back to the app (Claude, ChatGPT, Cursor...) and start the connection again from there. Do not bookmark or reuse the consent page address.

The app asks you to sign in again — the connection was revoked (in Connected apps, or by deleting its API key) or has been unused for a long time. Connect again; nothing else is needed.

The connector is added but no tools appear — check that the URL ends in /mcp, that the connector is switched on for the chat, and that the connection shows as connected in the app's connectors list. In Claude Code, run /mcp to see the status.

Errors from tools — Project not found, Invalid movie, and out-of-credits messages are the same as in the local server. See Common errors.

Corporate networks — the AI apps call JSON2Video from their own servers, so your firewall does not matter for claude.ai and ChatGPT. For Claude Code, Cursor and VS Code, allow outbound HTTPS to mcp.json2video.com and json2video.com.

Local MCP server

The local server is the @json2video/cli package. It runs on your computer, uses your API key, and can read and upload files from your disk. Choose it when you work offline, in CI, with a stdio-only editor, or when you need to upload local files.

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 run — 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 (plugin)

The JSON2Video plugin installs the MCP server in one step and asks for your API key, which Claude Code stores securely. Run this in Claude Code:

/plugin install json2video --marketplace JSON2Video/json2video-mcp

On older Claude Code versions, add the marketplace first:

/plugin marketplace add JSON2Video/json2video-mcp
/plugin install json2video@json2video

The plugin lives in the public JSON2Video/json2video-mcp repository. The server is also listed in the official MCP Registry as com.json2video/mcp.

Claude Code (`.mcp.json`)

The quickest way is to let the CLI write the config for you. Run this in your project folder:

json2video mcp install claude

It adds the json2video server to the project's .mcp.json and installs the create-video skill in .claude/skills/. Use cursor or vscode instead of claude for those editors.

For example prompts and a full walkthrough, see video editing with Claude Code. How this compares with the other ways to make videos with Claude is in Can Claude make videos?.

To configure it by hand instead, 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", "run"],
      "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", "run"],
      "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", "run"],
      "env": {
        "JSON2VIDEO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Reload the MCP servers from the Cascade panel.

Troubleshooting the local server

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", "run"].

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.
`save_template`	Validate a movie JSON and save it as a template in your account (or update one by ID). Returns the template ID, its variables and the editor link. For batches, save the design once and render each video with `template_id` + `variables`. Requires CLI 1.1.0 or later.
`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.
`list_recent_renders`	List your most recent renders (project ID, status, URL, duration) so the assistant can find a video again, for example after a timeout. Included in the remote server and in newer versions of the local server.
`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. The remote server accepts public URLs only, up to 50 MB.
`media_delete`	Delete a file from media.

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

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 run 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#

Remote MCP server (connect by URL)#

Before you start#

Connect from claude.ai and Claude Desktop#

Connect from ChatGPT#

Connect from Claude Code#

Connect from Cursor#

Connect from VS Code#

Sign in and consent#

Connected apps and revoking access#

Use an API key instead#

Limits and behavior#

Troubleshooting the remote server#

Local MCP server#

Install#

Configure your editor#

Claude Code (plugin)#

Claude Code (.mcp.json)#

Cursor#

Windsurf#

Troubleshooting the local server#

Tools the MCP exposes#

Common errors#