heygen-mcp

MCP server for the HeyGen avatar video API. Provides tools that any MCP-compatible client (Claude Desktop, Claude Code, etc.) can use to generate talking-avatar videos.

Setup

cd heygen-mcp
npm install

Set your API key (HeyGen dashboard → Settings → API):

export HEYGEN_API_KEY="your-key-here"

Test the server starts correctly:

node index.js
# Should print "HeyGen MCP server running" to stderr

Claude Desktop / Claude Code configuration

{
  "mcpServers": {
    "heygen": {
      "command": "node",
      "args": ["/Users/carlosvidal/www/heygen-mcp/index.js"],
      "env": { "HEYGEN_API_KEY": "your-key-here" }
    }
  }
}

Or from the CLI:

claude mcp add heygen -e HEYGEN_API_KEY=your-key-here -- node /Users/carlosvidal/www/heygen-mcp/index.js

Tools

create_video

Primary tool. Submits the video, polls until rendering finishes, returns the video_url, and optionally saves the mp4 to output_path.

Params: avatar_id, text, voice_id, talking_photo_id, audio_url, avatar_style, speed, emotion, locale, background, scenes, dimension, title, caption, output_path, timeout_seconds

generate_video

Submits the video and returns video_id immediately, without polling.

Params: same as create_video minus output_path / timeout_seconds

check_video

Status of a video by video_id — pending, waiting, processing, completed or failed. Returns video_url, thumbnail_url, gif_url, caption_url and duration when completed.

download_video

Saves a finished video to a local .mp4. Accepts video_id (URL looked up automatically) or a direct video_url.

list_avatars

Search avatars by name or ID. Always pass search — an account holds well over a thousand avatars. Set include_talking_photos to also match photo avatars.

list_voices

Search voices by search / language / gender. Returns voice_id, preview_audio, emotion_support and support_locale.

list_videos

Recent videos in the account, to recover a video_id generated earlier.

get_quota

Remaining API quota in seconds and credits. Run before long jobs.

Single scene vs. multi-scene

A single scene uses the flat arguments:

{ "avatar_id": "Piper_standing_education_front", "text": "Hola, soy Piper.", "voice_id": "1eca26cb..." }

Multiple scenes use scenes, which overrides the flat arguments. Each scene has its own avatar, script, voice and background:

{
  "scenes": [
    { "avatar_id": "avatar_a", "text": "Primera escena.", "voice_id": "voice_a",
      "background": { "type": "color", "value": "#f5f5f5" } },
    { "avatar_id": "avatar_b", "text": "Segunda escena.", "voice_id": "voice_b",
      "background": { "type": "image", "url": "https://example.com/bg.jpg" } }
  ],
  "dimension": "1080p_portrait",
  "title": "Demo"
}

Dimension presets

Preset	Size
1080p_landscape	1920x1080
720p_landscape (default)	1280x720
1080p_portrait	1080x1920
720p_portrait	720x1280
square	1080x1080

Notes

• Video URLs expire 7 days after generation — use output_path or download_video to keep them.
• Max 1500 characters of text per scene; split longer scripts across scenes.
• HeyGen bills 1 credit per 60 seconds of rendered video.
• Rendering typically takes 1–3 minutes; polling interval is 5 seconds, default timeout 300s.
• emotion only applies to voices with emotion_support: true; locale only to voices with support_locale: true.