MCP Server

The Hera MCP server lets AI assistants generate motion graphics videos on your behalf. It exposes the same capabilities as the REST API, but through the standardized Model Context Protocol — so your AI tools can call Hera directly.

Prerequisites

A Hera API key (see Authentication)

Available tools

The MCP server exposes three tools:

Tool	Description
`create_video`	Create a new video generation job from a text prompt and output configurations. Returns a `video_id` for polling.
`get_video`	Check the status of a video job and retrieve download URLs for completed outputs.
`upload_file`	Upload a file (image, video, audio, font, or CSV) for use as model input. Returns a hosted URL.

Setup

Claude Code
Codex
Cursor
VS Code
Other

Run the following command in your terminal:

claude mcp add --transport http hera https://mcp.hera.video/mcp --header "x-api-key: YOUR_API_KEY"

Run the following command in your terminal:

codex mcp add hera -- npx -y mcp-remote https://mcp.hera.video/mcp --header "x-api-key: YOUR_API_KEY"

Install in CursorTo open Cursor and automatically add the Hera MCP, click install. Alternatively, add the following to your .cursor/mcp.json file in your project:

{
  "mcpServers": {
    "hera": {
      "url": "https://mcp.hera.video/mcp",
      "type": "http",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Install in VS CodeTo open VS Code and automatically add the Hera MCP, click install. Alternatively, add the following to your .vscode/mcp.json file in your project:

{
  "servers": {
    "hera": {
      "type": "http",
      "url": "https://mcp.hera.video/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

MCP is an open protocol supported by many clients. Use the server URL https://mcp.hera.video/mcp and pass your API key via the x-api-key header. For example, a client might accept the following configuration:

{
  "hera": {
    "url": "https://mcp.hera.video/mcp",
    "headers": {
      "x-api-key": "YOUR_API_KEY"
    }
  }
}

Replace YOUR_API_KEY with your actual API key.

Example workflow

Once connected, you can ask your AI assistant to generate videos naturally:

“Create a 10-second 1080p MP4 video of a spinning globe with a blue gradient background”

Behind the scenes, the assistant will:

Call create_video with your prompt and output settings
Receive a video_id
Poll get_video until the status is success
Return the download URL

Tool reference

create_video

Creates a new video generation job. Parameters:

Parameter	Type	Required	Description
`prompt`	string	Yes	Text prompt describing the video to generate.
`outputs`	array	Yes	1-10 output configurations (see below).
`reference_image_url`	string	No	URL of a reference image.
`reference_image_urls`	string[]	No	Up to 5 reference image URLs.
`reference_video_url`	string	No	URL of a reference video.
`duration_seconds`	number	No	Duration in seconds (1-60).
`style_id`	string	No	Style ID for consistent branding.
`parent_video_id`	string	No	Video or template ID to use as a base.
`assets`	array	No	Array of asset objects (`{ type, url }`) to include. Use `upload_file` to get URLs.

Output configuration:

Field	Type	Options
`format`	string	`mp4`, `prores`, `webm`, `gif`
`aspect_ratio`	string	`16:9`, `9:16`, `1:1`, `4:5`
`fps`	string	`24`, `25`, `30`, `60`
`resolution`	string	`360p`, `480p`, `720p`, `1080p`, `4k`

Returns: video_id and project_url.

get_video

Retrieves the status and download URLs for a video job. Parameters:

Parameter	Type	Required	Description
`video_id`	string	Yes	The video ID returned by `create_video`.

Returns: video_id, status (in-progress, success, or failed), project_url, and an outputs array with individual status, download URL, config, and error (if any).

upload_file

Uploads a remote file to Hera’s CDN for use as model input. For local files, pass the local path and the tool will return a ready-to-use curl command. Parameters:

Parameter	Type	Required	Description
`url`	string	Yes	HTTP or HTTPS URL of the file to upload. For local files, pass the path to get a `curl` command.
`file_name`	string	No	Custom filename (e.g. `logo.png`). Inferred from the URL if omitted.

Supported types: images (PNG, JPEG, GIF, SVG, WebP, BMP), videos (MP4, MPEG, WebM, MOV, AVI, FLV, MPG, WMV, 3GP), audio (MP3, WAV, AAC), fonts (TTF, OTF, EOT, WOFF, WOFF2), and CSV. Max size: 10 MB. Returns: url — the hosted URL to pass to create_video fields like reference_image_url, reference_image_urls, reference_video_url, or assets.

Looking for support or have questions? Email us at [email protected].

Documentation Index

​Prerequisites

​Available tools

​Setup

​Example workflow

​Tool reference

​create_video

​get_video

​upload_file

Prerequisites

Available tools

Setup

Example workflow

Tool reference

create_video

get_video

upload_file