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 two 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.

Setup

Claude Code
Cursor
Windsurf
VS Code (Copilot)
Claude Desktop

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"

Open Settings > MCP and add a new server, or edit .cursor/mcp.json in your project:

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

Open Settings > MCP and add a new server, or edit ~/.codeium/windsurf/mcp_config.json:

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

Create or edit .vscode/mcp.json in your project:

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

Claude Desktop currently requires a stdio bridge. Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "hera": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.hera.video/mcp",
        "--header",
        "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.

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).

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

​Prerequisites

​Available tools

​Setup

​Example workflow

​Tool reference

​create_video

​get_video

Prerequisites

Available tools

Setup

Example workflow

Tool reference

create_video

get_video