Skip to main content

​
Prerequisites

  • Gemini CLI installed (npm install -g @google/gemini-cli@latest)
  • A HeyGen account with Video Agent access

​
Adding the MCP Server

Open your Gemini CLI settings file and add the HeyGen server under the mcpServers key. Global (all projects): ~/.gemini/settings.json Project-scoped: .gemini/settings.json in your project root 
{
  "mcpServers": {
    "heygen": {
      "httpUrl": "https://mcp.heygen.com/mcp/v1/"
    }
  }
}
If you already have other MCP servers configured, add heygen alongside them inside the existing mcpServers block. Restart Gemini CLI after saving the file.

​
Verifying the Connection

Launch Gemini CLI and run: 
/mcp
You should see heygen listed under connected MCP servers with its available tools displayed.

​
Authentication

On first tool invocation, Gemini CLI will prompt you to authorize access to your HeyGen account through a browser-based OAuth flow. Follow the prompt to complete authentication.

​
Usage

Once connected, prompt Gemini CLI with a video generation request: 
Generate a 60-second explainer video about our new API release using HeyGen.
Gemini 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 Gemini to reference 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.

​
Configuration Scoping

ScopeFile LocationAvailability
Global~/.gemini/settings.jsonAll projects
Project.gemini/settings.json (project root)Current project only