# HeyGen MCP

> HeyGen MCP Server automates video production using AI agents. This server lets you manage avatars, trigger studio-quality video generation, and translate videos—all without opening a GUI. Your agent handles the variables and status checks, letting you create talking head content at scale just by chatting with your client.

## Overview
- **Category:** ai-frontier
- **Price:** Free
- **Tags:** ai-avatars, video-generation, talking-head, content-creation, studio-quality, template-management

## Description

**HeyGen MCP Server automates your entire video workflow using AI agents.** You're connecting your HeyGen account so your agent—your client—can handle complex tasks, from avatar selection to multi-language translation. It treats your AI client like a dedicated production suite, letting you manage high-quality talking head content at scale without ever touching a graphical user interface. Your agent handles the variables and status checks; all you gotta do is chat with it.

**Finding What You Need: Avatars & Templates**

Before you generate anything, your agent needs to know what's available. It can list all video templates using `list_templates` or narrow down options by checking out the structure and required variables for any specific template ID with `get_template_details`. To nail down the perfect spokesperson, it first lists avatar categories via `list_avatar_groups`, then gets a comprehensive roster of every active avatar ID and name using `list_avatars`. This lets your agent make sure you're pointing to the right asset for any project.

**Generating Content: Two Ways to Go Live**

You can create videos in two distinct ways. If you need a full, studio-quality video with specific scenes and avatar configurations, your agent calls `generate_video` to manually start that production process. But if you're running bulk content—like updating product descriptions across fifty different locations—you use automation. Calling `generate_from_template` lets your agent automatically replace defined variables within a chosen template structure, spitting out multiple videos based on simple data inputs. This is how you create talking head content at scale.

**Localization and Translation**

Need to hit international markets? Your agent handles that too. Using `translate_video`, it converts an existing video into a completely different language while making sure the avatar's lips sync perfectly to the new audio track. It’s not just dubbing; it’s professional localization.

**Managing Jobs and History**

Since generation takes time, your agent needs ways to keep track of everything. After you trigger a job, you use `get_video_status` to check if the video is done, which returns the final download URL the second it’s ready. You don't wanna lose track of what worked—your agent can view a list of all previously generated videos using `list_videos`, providing basic metadata and status for archiving purposes. If you're doing live interaction or streaming sessions, it retrieves the full history records with `list_streaming_history`.

**How Your Agent Uses This Stuff:**

When you hook up your client to this server, you don't write API calls; your agent does that for you. It talks to the tools based on natural conversation. For instance, if you tell it, "Make a video about Q3 sales using Template X and Avatar Z," your agent first runs `get_template_details` to verify Template X works, then it uses `list_avatars` to get the ID for Avatar Z, and finally, it executes `generate_from_template`, automatically managing the variables and confirming the status until the final URL is ready. It's a closed loop—discovery, generation, verification, all through chat.

## Tools

### generate_from_template
Creates a video by replacing defined variables within an existing template structure.

### generate_video
Manually starts the process of creating a full studio-quality video using specified scenes and avatar details.

### get_api_profile
Retrieves basic usage information about your current HeyGen API account status.

### get_template_details
Fetches the structure and required variables for a specific video template ID.

### get_video_status
Checks if a generated video is complete, returning the final URL when ready.

### list_avatar_groups
Lists categories of available avatars to help narrow down your choices for generation.

### list_avatars
Provides a list of all active avatar IDs and names that can be used in video creation.

### list_streaming_history
Retrieves the history records for interactive, real-time streaming sessions.

### list_templates
Lists all available video templates you can use to automate content creation.

### list_videos
Shows a list of previously generated videos, including basic metadata and status.

### translate_video
Converts an existing video into another language while syncing the speaker's lips to match the new audio track.

## Prompt Examples

**Prompt:** 
```
List all available avatars and find one named 'Joshua'.
```

**Response:** 
```
I've retrieved the list of avatars. I found 'Joshua in Suit' (ID: joshua_v3) and 'Joshua Casual'. Would you like to use one of these for a video generation task?
```

**Prompt:** 
```
Show me the status of video ID 'vid_99283'.
```

**Response:** 
```
Checking video status... Your video 'vid_99283' is currently COMPLETED. You can watch it or download it here: [Watch Video](https://heygen.com/video/...) Should I retrieve your full video history?
```

**Prompt:** 
```
Generate a video from template 'welcome_v1' with variable {'name': 'John Doe'}.
```

**Response:** 
```
Template generation triggered! I've started the production of your video using the 'welcome_v1' template. This usually takes 2-5 minutes. I'll monitor the status for you. Should I notify you once the URL is ready?
```

## Capabilities

### Video Production
Manually trigger studio-quality videos using `generate_video`, or automate bulk content by replacing variables in templates with `generate_from_template`.

### Avatar & Template Discovery
List all available avatars (`list_avatars`) and retrieve the structure of any template using `get_template_details` before generating content.

### Video Localization
Translate an existing video into a new language while automatically syncing the avatar's lip movements via `translate_video`.

### Task Monitoring
Check if a job is finished and retrieve the final download URL by calling `get_video_status` after triggering generation.

### Content Archiving
View video history (`list_videos`) or track real-time interactive sessions with `list_streaming_history`.

## Use Cases

### Updating Global Training Modules
The L&D team needs to update a core HR video for German and Japanese staff. Instead of re-recording, the agent first calls `list_videos` to find the source ID, then uses `translate_video` twice (once for German, once for Japanese). The result is localized content ready for immediate use.

### Personalized Sales Outreach
A marketer needs to send 50 personalized videos. Instead of making 50 videos manually, the agent uses `list_templates` to find the 'Welcome' template, then loops through a list of clients calling `generate_from_template` for each one, swapping in their name and company.

### Quick Social Media Headshots
A content creator needs 10 random talking head videos today. They call `list_avatars` to pick a few different IDs, then use `generate_video` ten times with varying prompts and avatars. The agent manages the queue until all are done.

### Debugging Video Flow
A developer is writing an automation script and needs to confirm if the last generated video actually finished processing. Instead of waiting, they immediately call `get_video_status` with the job ID to get a definitive 'completed' status and URL.

## Benefits

- **Automate Content at Scale:** Forget manual video creation. Use `generate_from_template` to run personalized campaigns—just change the variables in your prompt, and the videos update automatically.
- **Never Lose a Video Link:** After running `generate_video`, don't guess if it worked. Call `get_video_status` until it returns 'completed' and gives you the final URL.
- **Global Content in Minutes:** Need to localize training? Use `translate_video`. It handles both the language switch *and* perfect lip-syncing, saving hours of manual post-production work.
- **Instant Avatar Selection:** Stop searching. First, call `list_avatars` to see every available avatar ID. Then pass that specific ID into your generation request for maximum control.
- **End-to-End Workflow:** Your agent can manage the whole cycle: Use `list_templates` -> Get details with `get_template_details` -> Run video -> Check status with `get_video_status`. It’s a single chat flow.

## How It Works

The bottom line is: you talk to your AI agent, and it runs all the complex video production logic behind the scenes.

1. Subscribe to the server and provide your HeyGen API Key (found in Developer Settings).
2. Your AI client calls a discovery tool, like `list_templates`, to gather required data or IDs.
3. The agent executes the final command (e.g., `generate_from_template`) and handles any necessary status checks using `get_video_status` until the URL is available.

## Frequently Asked Questions

**How do I find my HeyGen API Key?**
Log in to your HeyGen account, navigate to **User Settings**, and select the **Developer** tab. You will be able to generate and copy your unique API key from there.

**How can I generate a video using a template?**
First, use `list_templates` to find the template you want. Then, use the `generate_from_template` tool by providing the template ID and a JSON string mapping the variables (like text or image URLs) you want to replace.

**Can I translate existing videos into other languages?**
Yes! Use the `translate_video` tool. You must provide the source video URL and the target language code. HeyGen will generate a new version of the video with the translated audio and lip-syncing.

**Is the integration secure for creative data?**
Absolutely. The integration uses official HeyGen API keys over HTTPS. Your credentials are encrypted and stored securely within the Vinkius Cloud infrastructure.

**How do I check the status of a video job using the `get_video_status` tool?**
Run `get_video_status` with your unique video ID. The response tells you if the video is 'completed' and provides the final URL, or it flags an error, letting you know exactly what went wrong with the generation.

**How do I use `list_avatars` to find a specific avatar ID for my script?**
Executing `list_avatars` gives you a comprehensive list of every available persona and their required 'avatar_id'. You simply copy that unique ID from the response and pass it directly into your video generation request.

**What does running `get_template_details` show me before I generate content?**
This tool returns the full schema of any template. It shows you exactly what variables are required, their data types, and how many slots are available. This prevents your agent from trying to run a video with missing parameters.

**Can I use `list_videos` to retrieve my complete history of generated content?**
Yes, `list_videos` pulls all your past generation records into the conversation context. This lets your agent keep track of every video you've created and quickly reference specific IDs without needing to navigate a web interface.