> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hera.video/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Hera to your AI coding assistant via the Model Context Protocol.

The Hera MCP server lets AI assistants generate motion graphics videos on your behalf. It exposes the same capabilities as the [REST API](/api-reference/introduction), but through the standardized [Model Context Protocol](https://modelcontextprotocol.io/) — so your AI tools can call Hera directly.

## Prerequisites

* A Hera API key (see [Authentication](/api-reference/introduction#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

### Install with add-mcp

Install the MCP server for all your coding agents:

```bash theme={null}
npx add-mcp https://mcp.hera.video/mcp --header "x-api-key: YOUR_API_KEY"
```

<Tabs>
  <Tab title="Claude Code">
    Run the following command in your terminal:

    ```bash theme={null}
    claude mcp add --transport http hera https://mcp.hera.video/mcp --header "x-api-key: YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Codex">
    Run the following command in your terminal:

    ```bash theme={null}
    codex mcp add hera -- npx -y mcp-remote https://mcp.hera.video/mcp --header "x-api-key: YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Cursor">
    <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=hera&config=eyJ1cmwiOiJodHRwczovL21jcC5oZXJhLnZpZGVvL21jcCIsInR5cGUiOiJodHRwIiwiaGVhZGVycyI6eyJ4LWFwaS1rZXkiOiJZT1VSX0FQSV9LRVkifX0=" style={{display:'inline-flex',alignItems:'center',gap:'6px',backgroundColor:'#fa4d3d',color:'white',padding:'5px 12px',borderRadius:'6px',fontSize:'13px',fontWeight:500,textDecoration:'none'}}><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" /><polyline points="7 10 12 15 17 10" /><line x1="12" y1="15" x2="12" y2="3" /></svg> Install in Cursor</a>

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

    ```json theme={null}
    {
      "mcpServers": {
        "hera": {
          "url": "https://mcp.hera.video/mcp",
          "type": "http",
          "headers": {
            "x-api-key": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    <a href="vscode:mcp/install?%7B%22name%22%3A%22hera%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.hera.video%2Fmcp%22%2C%22headers%22%3A%7B%22x-api-key%22%3A%22YOUR_API_KEY%22%7D%7D" style={{display:'inline-flex',alignItems:'center',gap:'6px',backgroundColor:'#fa4d3d',color:'white',padding:'5px 12px',borderRadius:'6px',fontSize:'13px',fontWeight:500,textDecoration:'none'}}><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" /><polyline points="7 10 12 15 17 10" /><line x1="12" y1="15" x2="12" y2="3" /></svg> Install in VS Code</a>

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

    ```json theme={null}
    {
      "servers": {
        "hera": {
          "type": "http",
          "url": "https://mcp.hera.video/mcp",
          "headers": {
            "x-api-key": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other">
    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:

    ```json theme={null}
    {
      "hera": {
        "url": "https://mcp.hera.video/mcp",
        "headers": {
          "x-api-key": "YOUR_API_KEY"
        }
      }
    }
    ```
  </Tab>
</Tabs>

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:

1. Call `create_video` with your prompt and output settings
2. Receive a `video_id`
3. Poll `get_video` until the status is `success`
4. 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-120).                                                        |
| `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`.

<Note>
  Looking for support or have questions? Email us at [support@hera.video](mailto:support@hera.video).
</Note>