@mnicole-dev/heygen-mcp-server

MCP server for the HeyGen API — generate AI avatar videos, manage avatars, voices, templates, assets, and webhooks.

Tools (15)

| Tool | Description | |---|---| | generate-video | Generate an AI avatar video with custom text, voice and background | | generate-video-from-prompt | Generate a video from a plain text prompt (Video Agent) | | get-video-status | Poll video generation status (pending / processing / completed / failed) | | list-avatars | List all available avatars and talking photos | | list-voices | List available voices filtered by language and gender | | list-templates | List all video templates | | generate-from-template | Generate a video from a template with custom variables | | translate-video | Translate a video into another language | | get-translation-status | Poll video translation status | | list-assets | List video assets in your account | | delete-asset | Delete an asset by ID | | generate-photo-avatar | Generate an AI photo avatar | | list-webhooks | List webhook endpoints | | create-webhook | Create a webhook endpoint | | delete-webhook | Delete a webhook endpoint |

Setup

Environment variable

export HEYGEN_API_KEY="your_api_key_here"

Get your API key from app.heygen.com/settings → API.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "heygen": {
      "command": "npx",
      "args": ["-y", "@mnicole-dev/heygen-mcp-server"],
      "env": {
        "HEYGEN_API_KEY": "your_api_key_here"
      }
    }
  }
}

Usage notes

• Video generation is asynchronous: generate-video and generate-video-from-prompt return a video_id. Poll get-video-status until status is completed or failed.
• Same pattern for translation: translate-video returns a video_translate_id, poll get-translation-status.
• list-avatars and list-voices are capped at 50 results each to keep output manageable.
• generate-from-template expects variables as a JSON string matching HeyGen's template variable schema.

Response format

All HeyGen API responses use the envelope { error, data }. This server unwraps the envelope, raises on non-null error, and returns the data payload.

License

MIT