How to Connect HeyGen to Gemini via MCP

💡 No install? Use cloud.anythingmcp.com directly. Sign in, click Connectors → HeyGen, paste your credentials, mint an MCP API key and you're done. No Docker, no git clone, no local server.

HeyGen + Gemini

Let your AI make HeyGen avatar videos with your own key: pick avatars and voices, turn a script or a prompt into a talking video, fill your templates, translate videos into other languages with lip-sync, create photo avatars, and check renders and your balance.

Prerequisites

See the full setup instructions baked into the connector (visible in the in-app store when you select the connector). The required environment variables for this connector are:

HEYGEN_API_KEY

Step 1 — Get credentials

1. Sign in at https://app.heygen.com and open the API dashboard (https://app.heygen.com/developers/api).
2. Generate an API key and copy it. API usage is billed separately from a HeyGen web subscription: add balance or a payment method there if the account has none.
3. Paste the key into HEYGEN_API_KEY and install the connector. The key is sent only to HeyGen. A key restricted to some scopes needs read access to avatars, voices, videos, templates, translations and the user, and write access for the tools that create.
4. Start with heygen_get_account: it shows your billing type and what you have left to spend.

Billed to your HeyGen API balance: videos, translations and avatars are paid from your API balance (a pay-as-you-go wallet or your plan's credits). HeyGen bills video by length and engine; the current prices are in the API dashboard, and a refused call (402) says how much was needed. Listing and checking is free.

Confirm first: before heygen_create_video, heygen_generate_from_template, heygen_create_agent_video or heygen_translate_video, the AI tells you what will be made (avatar, voice, script length, format, languages, engine) and waits for your yes. heygen_create_photo_avatar only takes a photo of someone who agreed to it, such as yourself, and the AI asks you to confirm that you have that right. heygen_delete_video is switched off at install.

How a video is made:

1. The AI picks a character with heygen_list_avatar_groups and one of its looks with heygen_list_avatar_looks; the look is the presenter. A voice from heygen_list_voices is optional, otherwise the avatar's own voice speaks.
2. heygen_create_video takes the script (up to 5,000 characters), the format (for example 9:16 for shorts) and the engine, and returns a video id at once.
3. The video renders in the background. The AI checks heygen_get_video about every 30 seconds; a render takes from a minute to several minutes, longer for long scripts.
4. The finished video comes with an MP4 link, a captioned version, SRT subtitles and a link to the video in HeyGen. Download links expire; ask again for fresh ones.

Other ways to make a video:

• Templates: heygen_list_templates and heygen_get_template show your API-ready templates and their variables; heygen_generate_from_template fills every text variable and renders the video.
• Video Agent: heygen_create_agent_video turns a prompt into a whole video (script, scenes, avatar); heygen_get_agent_session follows it until the video renders.
• Translation: heygen_translate_video translates a video from a public link into one or more languages, with the speaker's cloned voice and lip-sync or as audio only; heygen_list_translation_languages lists the target languages.
• Photo avatar: heygen_create_photo_avatar makes a presenter from one portrait; heygen_get_avatar_look shows when it is ready to use.

Engines: avatar_iv is the default. avatar_v gives the most natural motion, but only for looks that support it. avatar_iii supports 4K for digital twins and studio avatars.

Limits: 10 videos, translations or agent sessions rendering at once on pay-as-you-go (more on Enterprise), 300 list calls and 500 status checks a minute. Source files must be public links: video up to 100 MB, audio up to 50 MB and 10 minutes.

Common errors: 401: the key is wrong or revoked. 402 insufficient_credit: the balance does not cover this video, and the message says how much is needed. usage_limit_reached or trial_limit_exceeded: a workspace or trial limit that an admin or a paid plan lifts. 403 insufficient_api_key_scope: the key is restricted; give it the scopes listed above. 400 invalid_parameter: the message names the field, for example an engine the look does not support. 404: an id that does not exist; the AI checks it with the list tools. 429: too many requests; wait and retry once later.

The connector uses HeyGen's API v3 (HeyGen retires the older v1 and v2 endpoints on 31 October 2026). It does not cover multi-scene studio videos, image-to-video, lip-sync of existing videos, voice cloning and voice design, text to speech on its own, interactive streaming avatars, file uploads (sources must be public links), proofreading translations, webhooks, brand kits, folders or batches.

Step 2 — Install the adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Step 3 — Add the connector in Gemini

Your server URL: in AnythingMCP, open MCP Servers → the server this connector is on, and copy its URL (https://cloud.anythingmcp.com/mcp/…). Use it wherever this guide shows YOUR_SERVER_ID.

Gemini CLI reads MCP servers from ~/.gemini/settings.json (on Windows %USERPROFILE%\.gemini\settings.json). Add:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Create an MCP API key in AnythingMCP under MCP Servers → your server → API keys, and paste it in place of YOUR_MCP_API_KEY.
2. Save the file and restart gemini.
3. Run /mcp inside Gemini CLI (or gemini mcp list in your shell): anythingmcp should show as connected.
4. Start prompting: Gemini CLI can now call the HeyGen tools.

Available tools

Example prompts

• "How much is left on my HeyGen API balance?"
• "Show me my own avatars and which of their looks work best in 9:16."
• "Make a 45-second 9:16 video with my digital twin reading this script. Confirm the avatar, voice and length with me first, then send me the MP4 link when it is ready."
• "Fill our weekly update template with these three news items and render it."
• "Translate this product demo video into Spanish (Spain) and Japanese with lip-sync and tell me when both versions are ready."

FAQ

Where does Gemini CLI look for MCP servers? In ~/.gemini/settings.json for your user, or in .gemini/settings.json inside a project. gemini mcp list shows each server and whether it connects.

Next steps

• Connector landing page
• Connect to Claude
• Connect to ChatGPT