heygen-mcp v2.0 — The complete HeyGen MCP server

35+ tools across 12 domains covering the full HeyGen API, plus unique productivity helpers that HeyGen's official MCP doesn't have.

Built for developers who want fine-grained control and cost-efficient workflows.

Why this over HeyGen's official MCP?

| Feature | Official HeyGen MCP | This (heygen-mcp v2.0) | |---------|:-------------------:|:----------------------:| | Auth | OAuth | API key (simpler in scripts) | | Install | Remote URL | Local npm (one-time npm install) | | Video generation | ✅ | ✅ | | Voice design | ✅ | ✅ | | TTS standalone | ✅ | ✅ | | Lip sync | ✅ | ✅ | | Video translation | ✅ | ✅ | | Photo Avatars | ✅ | ✅ | | Digital Twins | ✅ | ✅ | | Templates | ❌ | ✅ | | Webhooks | ✅ | ✅ | | Asset upload (binary) | ✅ | ✅ | | wait_for_completion one-shot polling | ❌ | ✅ unique | | download_video to local path | ❌ | ✅ unique | | save_video_to_project (wait + download combined) | ❌ | ✅ unique | | batch_from_scripts_folder | ❌ | ✅ unique | | find_best_voice (intelligent matching) | ❌ | ✅ unique | | Forkable / extensible | ❌ (hosted) | ✅ (your fork) |

Tool inventory (35 tools)

Account (2)

• heygen_get_user — profile + billing info
• heygen_get_quota — remaining credits per tier

Avatars (3)

• heygen_list_avatars — 2000+ avatars w/ gender + search filters
• heygen_list_avatar_groups — avatar characters
• heygen_list_avatars_in_group — looks within a group

Photo Avatars (5) — custom avatars from still photos

• heygen_create_photo_avatar_group
• heygen_generate_photo_avatar_looks
• heygen_train_photo_avatar
• heygen_photo_avatar_training_status
• heygen_photo_avatar_details

Digital Twins (3) — full-body avatars from video footage

• heygen_create_digital_twin
• heygen_digital_twin_status
• heygen_delete_digital_twin

Voices (4)

• heygen_list_voices — 2300+ voices w/ language/gender/engine filters
• heygen_design_voice — natural-language voice design (up to 3 candidates)
• heygen_generate_speech — TTS standalone (starfish engine)
• heygen_list_brand_voices — custom cloned voices

Videos (6)

• heygen_create_video — avatar + voice + script
• heygen_create_video_agent — conversational mode
• heygen_video_agent_status
• heygen_video_status
• heygen_list_videos
• heygen_delete_video

Video Translation (3)

• heygen_list_translation_languages
• heygen_translate_video
• heygen_translation_status

Lip Sync (2)

• heygen_create_lipsync — replace audio in existing video + re-animate lips
• heygen_lipsync_status

Templates (3)

• heygen_list_templates
• heygen_get_template
• heygen_generate_from_template

Assets (1)

• heygen_upload_asset — image / video / audio / pdf (max 32 MB)

Webhooks (4)

• heygen_list_webhook_endpoints
• heygen_list_webhook_events
• heygen_add_webhook
• heygen_delete_webhook

Helpers (5) — the unique productivity layer

• heygen_wait_for_completion — poll any async job (video/lipsync/translation/photo_avatar/digital_twin) until done, single call
• heygen_download_video — download URL to local file
• heygen_save_video_to_project — wait + download combined
• heygen_batch_from_scripts_folder — read markdown scripts, extract ES/EN blocks, generate videos in batch
• heygen_find_best_voice — intelligent match by language + gender + vibe

Setup

git clone https://github.com/Bananoman/HeyGenMCP.git
cd HeyGenMCP
npm install
npm run build

Register in Claude Code

{
  "mcpServers": {
    "heygen": {
      "command": "node",
      "args": ["/path/to/HeyGenMCP/dist/index.js"],
      "env": { "HEYGEN_API_KEY": "sk_V2_..." }
    }
  }
}

Restart Claude Code. All 35 tools available as heygen_*.

Example: generate 15 walkthrough videos in one agent turn

1. heygen_get_quota                           → confirm credits
2. heygen_find_best_voice(language="Spanish", gender="Male", vibe="warm")
                                              → voice_id
3. heygen_list_avatars(gender="male", search="construction")
                                              → pick avatar_id
4. heygen_batch_from_scripts_folder(
     scripts_folder="/path/to/scripts/",
     avatar_id, voice_id,
     language="ES", limit=15,
     ratio="16:9", background_color="#F97316"
   )                                          → 15 video_ids
5. For each: heygen_save_video_to_project(video_id, output_path="./videos/01.mp4")
                                              → all MP4s saved locally

Architecture

• TypeScript ESM, Node 20+
• axios + axios-retry for HTTP (3 retries on 429/5xx with exponential backoff)
• bottleneck rate limiter (3 concurrent, 300ms spacing) respects HeyGen's API tier
• zod for input validation
• Single file (src/index.ts, ~1200 lines) with clear domain sections — easy to fork and extend

License

MIT — fork freely.