Heygen MCP

🚀 Heygen MCP Server

Heygen MCP Server enables any MCP client (such as Claude Desktop or a proxy) to generate avatars and videos via the Heygen API.

⚠️ Important Note

This project is still in the early stages of development. While we welcome community feedback and contributions, please note that official support is limited.

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• Heygen API key (obtained from Heygen), including 10 free monthly credits.

Install uv

uv is a fast Python package installer and resolver. We recommend using it to install this package.

macOS or Linux:

# Install using the official installation script
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or via Homebrew (macOS)
brew install uv

Windows:

# Use the official installation script in PowerShell
irm https://astral.sh/uv/install.ps1 | iex

# Or via Scoop
scoop install uv

For other installation methods, refer to the uv documentation.

💻 Usage Examples

Quick Start with Claude Desktop

1. Obtain your API key from Heygen.
2. Install the uv package manager (see the Install uv section above).
3. Navigate to Claude > Settings > Developer > Edit Configuration > claude_desktop_config.json and add the following:

{
  "mcpServers": {
    "HeyGen": {
      "command": "uvx",
      "args": ["heygen-mcp"],
      "env": {
        "HEYGEN_API_KEY": "<Insert your API key here>"
      }
    }
  }
}

If you are using Windows, ensure that "Developer Mode" is enabled in Claude Desktop to use the MCP server. Click the hamburger menu on the left side of the menu bar, select "Help", and then select "Enable Developer Mode".

Available MCP Tools

The server provides the following tools for Claude:

• get_remaining_credits: Retrieve the remaining credits in your Heygen account.
• get_voices: Retrieve a list of available voices from the Heygen API (limited to the first 100 voices).
• get_avatar_groups: Retrieve a list of Heygen avatar groups.
• get_avatars_in_avatar_group: Retrieve a list of avatars in a specific Heygen avatar group.
• generate_avatar_video: Generate a new avatar video using the specified avatar, text, and voice.
• get_avatar_video_status: Retrieve the status of a video generated via the Heygen API.

🔧 Technical Details

Run with MCP Inspector

To run the server locally for testing and debugging using MCP Inspector:

uv --with "mcp[cli]" dev heygen_mcp/server.py

This will start the server in development mode and allow you to test the available tools and their functionality using MCP Inspector.

📚 Documentation

Roadmap

• [ ] Testing
• [ ] CI/CD
• [ ] Support for the photo avatar API
• [ ] Support for SSE and the OAuth process for remote MCP servers
• [ ] Support for the translation API
• [ ] Support for the template API
• [ ] Support for the interactive avatar API

Contribution

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is released under the MIT License. For more details, see the LICENSE file.