HeyGen MCP Server
Enables GitHub Copilot to generate AI avatar videos, manage templates, and work with assets through natural language commands using HeyGen's API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@HeyGen MCP Server Generate an AI avatar video with the script 'Welcome to my channel'."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
HeyGen MCP Server

⚠️ Disclaimer: This is a community fork of the original HeyGen MCP server, which appears to be abandoned. This is not an official HeyGen repository. Use at your own discretion.
Generate AI Videos with Natural Language - A Model Context Protocol (MCP) server for HeyGen API integration with AI assistants.
The HeyGen MCP server enables AI assistants (GitHub Copilot, Claude, ChatGPT) to generate AI avatar videos, manage templates, and work with assets through natural language commands.
🚀 Quick Start (1 Minute)
Requirements: Python 3.10+ | HeyGen API Key (get one here - 10 free credits/month)
⭐ Recommended: VS Code Extension (One-Click Setup)
Fastest way to get started - everything configured automatically:
Install from VS Code Marketplace →
The extension handles server registration and API key configuration automatically!
Related MCP server: Tavus MCP Server
Installation
Prerequisites
Python 3.10 or higher
A Heygen API key (get one from Heygen). Includes 10 Free Credits per Month
Install from PyPI
Install the package directly using pip or uv:
# Using pip
pip install heygen-mcp-sbroenne
# Using uv (recommended)
uv pip install heygen-mcp-sbroenne
# Or run directly without installing (uvx)
uvx heygen-mcp-sbroenneInstall from GitHub Releases
Download pre-built packages from GitHub Releases:
Download the
.whlor.tar.gzfile from the latest releaseInstall with pip:
pip install heygen_mcp_sbroenne-*.whl
For the VS Code extension, download the .vsix file and install via:
VS Code → Extensions →
...menu → "Install from VSIX..."
Usage
VS Code Extension (Recommended)
The easiest way to use HeyGen MCP with VS Code is through the community VS Code extension:
Install the extension:
Or search for "sbroenne.heygen-mcp" in VS Code Extensions (Ctrl+Shift+X)
Configure your API key:
Use Command Palette (Ctrl+Shift+P)
Search for "HeyGen: Configure API Key"
Enter your API key
Start using it:
The HeyGen MCP server will automatically be available to your AI assistant
Ask your AI assistant to generate videos, manage templates, etc.
See vscode-extension/README.md for more details.
Quickstart with Claude Desktop
Get your API key from HeyGen.
Install uv package manager (see Installing uv section above).
Go to Claude > Settings > Developer > Edit Config >
claude_desktop_config.jsonto include the following:
{
"inputs": [
{
"id": "heygen-api-key",
"type": "promptString",
"description": "HeyGen API Key",
"password": true
}
],
"mcpServers": {
"HeyGen": {
"command": "uvx",
"args": ["heygen-mcp-sbroenne"],
"env": {
"HEYGEN_API_KEY": "${input:heygen-api-key}"
}
}
}
}If you're using Windows, you'll need to enable "Developer Mode" in Claude Desktop to use the MCP server. Click "Help" in the hamburger menu at the top left and select "Enable Developer Mode".
Using with VS Code (Manual Configuration)
Add the following to your VS Code settings (.vscode/mcp.json):
{
"inputs": [
{
"id": "heygen-api-key",
"type": "promptString",
"description": "HeyGen API Key",
"password": true
}
],
"servers": {
"HeyGen": {
"type": "stdio",
"command": "uvx",
"args": ["heygen-mcp-sbroenne"],
"env": {
"HEYGEN_API_KEY": "${input:heygen-api-key}"
}
}
}
}Using a Local Development Version
If you want to run from a local clone (for development or testing), use uv run instead of uvx:
{
"inputs": [
{
"id": "heygen-api-key",
"type": "promptString",
"description": "HeyGen API Key",
"password": true
},
{
"id": "heygen-mcp-path",
"type": "promptString",
"description": "Path to local heygen-mcp repository"
}
],
"mcpServers": {
"HeyGen": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"--directory",
"${input:heygen-mcp-path}",
"python",
"-m",
"heygen_mcp.server"
],
"env": {
"HEYGEN_API_KEY": "${input:heygen-api-key}"
}
}
}
}For VS Code, use servers instead of mcpServers.
Available MCP Tools
The server provides 7 resource-based tools, each with multiple actions:
user - User Account Management
Action | Description |
| Get user profile information |
| Get remaining credits/quota |
voices - Voice Management
Action | Description |
| Get available voices (max 100, private voices first) |
avatars - Avatar Management
Action | Parameters | Description |
| - | Get all avatars and talking photos |
|
| Get details for a specific avatar |
|
| Get avatar groups |
|
| Get avatars in a specific group |
videos - Video Generation
Action | Parameters | Description |
|
| List all videos with pagination |
|
| Create a new avatar video |
|
| Create Avatar IV video from photo |
|
| Check video processing status |
✨ Video Background Support - Generate videos with color, image, or video backgrounds. See Video Backgrounds Guide for details.
templates - Template Management
Action | Parameters | Description |
| - | Get all templates in your account |
|
| Get template details including variables |
|
| Create video from template |
assets - Asset Management
Action | Parameters | Description |
| - | Get all assets (images, videos, audios) |
|
| Upload a media file, returns asset_id |
|
| Remove an asset |
folders - Folder Management
Action | Parameters | Description |
| - | Get all folders |
|
| Create a new folder |
|
| Delete a folder |
Example Usage:
# Get remaining credits
user(action="credits")
# List all avatars
avatars(action="list")
# Get specific avatar details
avatars(action="get", avatar_id="avatar_123")
# Generate a video (single scene)
videos(action="generate", video_inputs_json='[{"character": {"avatar_id": "..."}, "voice": {"voice_id": "...", "input_text": "Hello!"}}]')Development
Setup
# Clone the repository
git clone https://github.com/sbroenne/heygen-mcp.git
cd heygen-mcp
# Install dependencies
uv sync --dev
# Install pre-commit hooks
uv run pre-commit installPre-commit Hooks
This project uses pre-commit to run checks before each commit:
ruff - Linting and auto-fixing
ruff-format - Code formatting
pyright - Type checking
trailing-whitespace - Remove trailing whitespace
end-of-file-fixer - Ensure files end with newline
check-yaml - Validate YAML files
Run hooks manually on all files:
uv run pre-commit run --all-filesRunning with MCP Inspector
To run the server locally with the MCP Inspector for testing and debugging:
uv run mcp dev heygen_mcp/server.pyThis will start the server in development mode and allow you to use the MCP Inspector to test the available tools and functionality.
Running Tests
# Run all tests (requires HEYGEN_API_KEY in .env)
uv run pytest tests/ -v
# Skip video generation tests (uses credits)
uv run pytest tests/ -v -k "not video_generation"LLM Integration Tests
This project includes LLM-based tests using agent-benchmark to validate that AI assistants can correctly understand and use the MCP tools.
cd tests/heygen_mcp_llm_tests
# List available test scenarios
python run_llm_tests.py --list
# Run safe tests (read-only, no credits consumed)
python run_llm_tests.py
# Run a specific scenario
python run_llm_tests.py -s user-credits-testRequirements: Azure OpenAI endpoint (AZURE_OPENAI_ENDPOINT) and HeyGen API key (HEYGEN_API_KEY).
See tests/heygen_mcp_llm_tests/README.md for full documentation.
Roadmap
Tests (integration tests + MCP server smoke tests)
Template API Support
CI/CD (GitHub Actions + PyPI release)
Photo Avatar APIs Support
SSE And Remote MCP Server with OAuth Flow
Translation API Support
Interactive Avatar API Support
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
For maintainers: see the Publishing Guide for release instructions.
Related Projects
Windows MCP Servers - Collection of Windows-focused MCP servers
ExcelMcp - MCP Server for Microsoft Excel automation
OBS Studio MCP - MCP Server for OBS Studio screen recording
agent-benchmark - Framework for testing LLM + MCP integrations
License
This project is licensed under the MIT License - see the LICENSE file for details.
Available Tools
7 toolsassetsA
Upload and manage media files (images, videos, audio). USE CASES: backgrounds, Avatar IV photos, custom audio. Actions: 'list' - get all assets with id, name, type, and url; 'upload' - upload file (REQUIRED: file_path; returns asset_id); 'delete' - remove asset (REQUIRED: asset_id). NOTE: For Avatar IV, upload photo first - asset_id is the image_key.
Inputs: action (required), file_path, asset_id.
avatarsA
Get available avatars (AI personas) for video generation. REQUIRED: You need an avatar_id to generate videos. Actions: 'list' - get all avatars with id, name, gender (START HERE); 'get' - get details for a specific avatar (requires avatar_id); 'list_groups' - get avatar groups (include_public=true for public); 'list_in_group' - get avatars in a group (requires group_id). TIP: Use 'list' first, then 'get' for details on a chosen avatar.
Inputs: action (required), avatar_id, group_id, include_public.
foldersA
Organize videos and assets into folders. OPTIONAL: Use folders to keep your HeyGen workspace organized. Actions: 'list' - get all folders with id and name; 'create' - create a new folder (REQUIRED: name); 'rename' - rename a folder (REQUIRED: folder_id, name); 'trash' - move folder to trash (REQUIRED: folder_id); 'restore' - recover folder from trash (REQUIRED: folder_id).
Inputs: action (required), folder_id, name.
templatesA
Use pre-made video templates for easier video creation. EASIER THAN 'videos': Templates have pre-configured layouts. WORKFLOW: 1) 'list' templates, 2) 'get' to see variables, 3) 'generate' with variables, 4) Check status. Actions: 'list' - get all templates with id and name; 'get' - get template variables (REQUIRED: template_id); 'generate' - create video (REQUIRED: template_id; OPTIONAL: variables dict, title, test=True, caption=True). TIP: Use test=True to preview without using credits.
Inputs: action (required), template_id, variables, title, +2 more.
userA
Manage HeyGen user account. RECOMMENDED: Call 'credits' before generating videos to check quota. Actions: 'info' - get user profile (username, email, plan); 'credits' - get remaining credits (IMPORTANT: check before video generation).
Inputs: action (required).
videosA
Generate AI avatar videos and check their status. WORKFLOW: 1) Get avatar_id, 2) Get voice_id, 3) Call 'generate', 4) Poll 'status' until complete. Actions: 'list' - get all videos (with status and video_url if complete); 'generate' - create video (REQUIRED: video_inputs_json - JSON array of scenes, even for single-scene videos. Each scene needs: character.avatar_id, voice.input_text, voice.voice_id. Optional: background with type/value/asset_id); 'generate_iv' - create video from photo with AI motion (REQUIRED: image_key, script, voice_id, video_title); 'status' - check if ready (REQUIRED: video_id). NOTE: Videos take 1-10+ min. Poll status until completed.
Inputs: action (required), video_id, title, token, +9 more.
voicesA
Get available voices for video generation. REQUIRED: You need a voice_id to generate any video. Actions: 'list' - returns voices with id, name, language, gender. TIP: Match voice language to your script language.
Inputs: action (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: assets for media files, avatars for AI personas, folders for organization, templates for pre-made layouts, user for account info, videos for generation and status, voices for voice selection. No overlap in functionality.
All tool names are simple plural nouns (assets, avatars, folders, templates, videos, voices) with 'user' being the only singular, which is common and does not break consistency.
7 tools cover the essential aspects of a video generation platform: asset management, avatar/voice selection, template usage, video generation, folder organization, and user account. The count is well-scoped and not excessive.
The tool set covers the main workflow from asset upload to video generation and status checking. Minor gaps like lack of video deletion or account updates exist, but core functionality is complete.
Maintenance
Related MCP Connectors
Image and video AI tools and your own pipelines, run from any AI assistant.
Create and edit videos, images, voiceovers, music, and avatars with the VideoGen API.
Connect your AI agent to 300+ methods and 100+ live tools
Turn long videos into short, captioned viral clips from your AI assistant. 28 tools, OAuth.
Related MCP Servers
AlicenseNot gradedqualityNot gradedmaintenanceEnables Claude Desktop and Agents to generate AI avatars and videos through the HeyGen API, providing tools to create and manage avatar videos with specified text and voice options.191 PyPI44MIT- AlicenseBqualityDmaintenanceEnables AI video generation, replica management, conversational AI, lipsync, and speech synthesis through the Tavus API. Provides 29 tools across Phoenix replicas, video generation, personas, lipsync, and text-to-speech capabilities.292MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to generate images and videos through natural language using ImaginePro's API. Supports text-to-image generation, video creation, image upscaling, variants, inpainting, and multi-modal generation with real-time progress tracking.820 npmMIT
- AlicenseNot gradedqualityDmaintenanceProvides a standardized interface for interacting with Heygen's AI video generation tools and services through a unified API.MIT