home / mcp / heygen mcp server

Heygen MCP Server

Provides HeyGen avatar/video generation via MCP with a local uvx-based server and API key.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "heygen-com-heygen-mcp": {
      "command": "uvx",
      "args": [
        "heygen-mcp"
      ],
      "env": {
        "HEYGEN_API_KEY": "<insert-your-api-key-here>"
      }
    }
  }
}

You can run a HeyGen MCP Server to let MCP Clients like Claude Desktop access the HeyGen API for generating avatars and videos. This server acts as a bridge, exposing HeyGen capabilities through standard MCP tools so you can automate avatar creation and video generation from your client workflows.

How to use

Set up the MCP server in your client configuration so you can call HeyGen endpoints from Claude Desktop or other MCP clients. You’ll provide your HeyGen API key and run the MCP server locally or remotely, then use the available tools to check credits, browse voices and avatars, and generate avatar videos.

To connect from Claude Desktop, configure the MCP server using the provided MCP setup snippet. This wiring tells Claude where to run the MCP server and which API key to use.

Available tools you can use through the MCP server include getting remaining credits, listing voices and avatar groups, listing avatars within a group, generating avatar videos, and checking video status. Use these tools from your MCP client as part of your avatar/video automation workflows.

How to install

Prerequisites you need before starting include Python 3.10 or higher and a HeyGen API key (you can obtain one from HeyGen; it includes 10 free credits per month). You will also install the uv package manager to simplify MCP server execution.

Install uv on macOS or Linux with the official installer script or via Homebrew, then use Windows installation options if you’re on Windows.

# Install with the official uv installer script (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or via Homebrew (macOS)
brew install uv
```
```powershell
# Install with the official uv installer script in PowerShell (Windows)
ir https://astral.sh/uv/install.ps1 | iex

# Or via Scoop
scoop install uv

Configuration and usage notes

Create a configuration in your MCP client for the HeyGen MCP server. Include the MCP server name, the command to run uvx with the appropriate argument, and your HeyGen API key as an environment variable.

If you are using Windows, enable Developer Mode in Claude Desktop to allow MCP server execution. Open the Help menu, choose Enable Developer Mode, and then proceed with the configuration.

Security and keys

Keep your HeyGen API key secure. Do not share it in public configurations. Use environment variables to inject the key into the MCP server process at runtime.

Available tools

get_remaining_credits

Retrieves the remaining credits in your Heygen account.

get_voices

Retrieves a list of available voices from the Heygen API (limited to the first 100 voices).

get_avatar_groups

Retrieves a list of Heygen avatar groups.

get_avatars_in_avatar_group

Retrieves a list of avatars within a selected avatar group.

generate_avatar_video

Generates a new avatar video using the chosen avatar, input text, and voice.

get_avatar_video_status

Checks the status of a video generated via the Heygen API.