Claude Code - HeyGen Documentation

Connect HeyGen’s Video Agent to Claude Code to generate AI avatar videos directly from your terminal. Once configured, Claude Code can script, render, and deliver videos through natural-language prompts without leaving your development workflow.

Prerequisites

Claude Code installed (installation guide)
Node.js installed (required for MCP server resolution)
A HeyGen account with Video Agent access

Adding the MCP Server

Run the following command in your terminal (not inside the Claude Code CLI):

claude mcp add --transport http heygen https://mcp.heygen.com/mcp/v1/

To make the server available across all projects, add the -s user scope flag:

claude mcp add --transport http -s user heygen https://mcp.heygen.com/mcp/v1/

Alternative: Direct Config Edit

You can also add the server by editing ~/.claude.json directly:

{
  "mcpServers": {
    "heygen": {
      "type": "http",
      "url": "https://mcp.heygen.com/mcp/v1/"
    }
  }
}

Restart Claude Code after editing the config file.

Authentication

On first use, Claude Code will prompt you to authenticate with HeyGen. Run /mcp inside Claude Code and follow the browser-based OAuth flow to authorize access.

Verifying the Connection

After setup, confirm the server is active:

claude mcp list

Or from inside Claude Code:

/mcp

You should see heygen listed with a connected status.

Usage

Once connected, prompt Claude Code with a video generation request:

Generate a 60-second explainer video about our new API endpoints using HeyGen.

Claude Code will call HeyGen’s Video Agent to handle scripting, avatar selection, and rendering. Completed videos are accessible from the Projects page in your HeyGen dashboard.

Loading HeyGen Skills (Recommended)

For better prompt structure and higher-quality output, instruct Claude Code to read HeyGen’s prompt engineering guidelines before generating:

Before writing any video prompts, read the HeyGen skills at:
https://github.com/heygen-com/skills

Follow SKILL.md, references/prompt-optimizer.md, and references/video-agent.md
to structure each prompt with scenes, timing, visual style, and copy rules.

Scoping

Scope	Flag	Config Location	Availability
Local (default)	none	`.mcp.json` in project directory	Current project only
User	`-s user`	`~/.claude.json`	All projects for current user

​Prerequisites

​Adding the MCP Server

​Alternative: Direct Config Edit

​Authentication

​Verifying the Connection

​Usage

​Loading HeyGen Skills (Recommended)

​Scoping