Skip to main content
Glama

HeyGen MCP Server

VS Code Marketplace Installs PyPI Downloads GitHub Downloads

CI Release PyPI Version

License: MIT Python Built with Copilot

HeyGen Logo

⚠️ 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)

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-sbroenne

Install from GitHub Releases

Download pre-built packages from GitHub Releases:

  1. Download the .whl or .tar.gz file from the latest release

  2. Install 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

The easiest way to use HeyGen MCP with VS Code is through the community VS Code extension:

  1. Install the extension:

  2. Configure your API key:

    • Use Command Palette (Ctrl+Shift+P)

    • Search for "HeyGen: Configure API Key"

    • Enter your API key

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

  1. Get your API key from HeyGen.

  2. Install uv package manager (see Installing uv section above).

  3. Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to 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

info

Get user profile information

credits

Get remaining credits/quota

voices - Voice Management

Action

Description

list

Get available voices (max 100, private voices first)

avatars - Avatar Management

Action

Parameters

Description

list

-

Get all avatars and talking photos

get

avatar_id

Get details for a specific avatar

list_groups

include_public (optional)

Get avatar groups

list_in_group

group_id

Get avatars in a specific group

videos - Video Generation

Action

Parameters

Description

list

token (optional)

List all videos with pagination

generate

video_inputs_json (JSON array of scenes), title (optional)

Create a new avatar video

generate_iv

image_key, script, voice_id, video_title, motion options

Create Avatar IV video from photo

status

video_id

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

list

-

Get all templates in your account

get

template_id

Get template details including variables

generate

template_id, variables (optional), title, test, caption

Create video from template

assets - Asset Management

Action

Parameters

Description

list

-

Get all assets (images, videos, audios)

upload

file_path

Upload a media file, returns asset_id

delete

asset_id

Remove an asset

folders - Folder Management

Action

Parameters

Description

list

-

Get all folders

create

name

Create a new folder

delete

folder_id

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 install

Pre-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-files

Running with MCP Inspector

To run the server locally with the MCP Inspector for testing and debugging:

uv run mcp dev heygen_mcp/server.py

This 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-test

Requirements: 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.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Available Tools

7 tools
assetsA

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

    A4.3/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers