Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.heygen.com/llms.txt

Use this file to discover all available pages before exploring further.

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

ScopeFlagConfig LocationAvailability
Local (default)none.mcp.json in project directoryCurrent project only
User-s user~/.claude.jsonAll projects for current user