HeyGen MCP Claude Setup: Remote MCP Server for Avatar Videos

You type one sentence into Claude, step away for a coffee, and come back to a finished avatar video with a link you can send to a client. That is the promise of the HeyGen remote MCP server, and the setup takes about five minutes because there is nothing to install. No local server, no API credential pasted into a config file, no separate billing. You sign in once through OAuth and Claude can work inside your HeyGen account.

This walkthrough takes you through the HeyGen MCP Claude setup for the three places people actually run Claude: the web app, the desktop app, and Claude Code. You get the exact endpoint, the exact terminal command, prompts that produce usable videos, the credit and rate limit facts from HeyGen's own documentation, and a fix list for the errors that trip people up. Near the end there is a short tutorial for running HeyGen's Avatar V engine directly on PicassoIA, for the days when you want a talking presenter without opening an assistant at all.

💡 Quick answer: The endpoint is https://mcp.heygen.com/mcp/v1/. Add it to Claude as a custom connector (or run one claude mcp add command in Claude Code), approve the OAuth login, then ask for a video.

What the Remote MCP Actually Does

MCP stands for Model Context Protocol, the open standard that lets an AI assistant call tools inside other apps. HeyGen runs its server on its own infrastructure, so Claude talks to a hosted endpoint instead of a program on your laptop. According to the documentation, usage draws on the credits already included in your HeyGen plan, and the connector works on every plan.

Once connected, Claude can handle real production work from a chat window:

• Write and render from one prompt. HeyGen's Video Agent picks the avatar, drafts the script, builds the scenes and renders the result.
• Direct an avatar. A HeyGen avatar, or an image you supply, speaks your exact script with lip sync.
• Translate finished videos into other languages while keeping the mouth movement matched.
• Manage the library. List, fetch and delete videos, plus work with templates, brand kits and folders.
• Handle voices. Browse a catalog of 500+ voices, design a new one from a text description, or clone one from an audio file.

HeyGen counts more than 48 functions on the server and lists support for Claude (web, desktop and Code), Cursor, Gemini CLI, Codex CLI, Lovable, Manus, Superhuman and OpenAI-based agents, plus any custom MCP client.

Hosted, Not Installed

Community HeyGen servers published earlier run on your own machine and want an API credential sitting in an environment variable. The remote server removes both chores. Authentication is OAuth, so no secret lives in a config file, and HeyGen maintains the tools on its side. You paste one URL and approve one login screen.

Pick Your Setup Path

HeyGen documents three ways to let an agent work with the platform. Credits come from your plan in every case.

💡 HeyGen's advice for agents is blunt: try the MCP server first, fall back to the CLI, and use raw API calls last. Never paste an API credential into a chat window.

Connect HeyGen to Claude

Claude Web and Desktop

The menu labels shift slightly between app versions, but the flow is always the same.

1. Open Claude and go to Settings, then Connectors.
2. Search for HeyGen. If it is listed, click Connect. If not, choose Add custom connector.
3. Name it HeyGen and paste https://mcp.heygen.com/mcp/v1/.
4. Click Connect. A browser tab opens on HeyGen's OAuth screen.
5. Sign in to the HeyGen account whose credits you want to spend, then approve access.
6. Open a new chat and confirm the HeyGen connector is switched on for it.

The OAuth step is the one that matters most. Credits belong to whichever account you approve, so double check that you are signed in to the right workspace before you click through.

💡 Running a custom agent on its own domain? HeyGen asks you to submit that domain through its integration intake form so it can be whitelisted.

Claude Code in One Command

Run this once in your terminal:

claude mcp add --transport http heygen https://mcp.heygen.com/mcp/v1/

Copy Prompt

Then open Claude Code, type /mcp, pick heygen, and finish the OAuth sign in through your browser. Add --scope user if you want the server available in every project instead of only the current one.

Teams that share a repository can commit a project config instead:

{
  "mcpServers": {
    "heygen": {
      "type": "http",
      "url": "https://mcp.heygen.com/mcp/v1/"
    }
  }
}

Copy Prompt

The file holds no credentials, so each teammate authenticates on their own and credits stay tied to the person who asked for the video.

Verify the Connection

Ask Claude: "Call the HeyGen get_current_user tool and tell me which account is connected." HeyGen's own docs use this call as the health check. In Claude Code the tool appears as mcp__heygen__get_current_user. If the account name matches what you expect, you are ready. If Claude says it has no HeyGen tools, jump to the fix table further down.

Make Your First Avatar Video

Rendering is asynchronous. HeyGen says videos typically finish in 1 to 5 minutes, and Claude has to call a status tool to find out when. Say so in your prompt, or the assistant may hand you an ID and stop.

Prompts That Work

The Video Agent is the shortest route from idea to video. It has two modes: generate fires and forgets, while chat lets you refine across several turns. A strong prompt names six things:

• Goal: what the viewer should do after watching
• Audience: who is watching
• Length: 15, 30 or 60 seconds
• Tone: calm, upbeat or formal
• Format: 16:9 widescreen or vertical 9:16
• Style: one pick from the style list

"Use HeyGen Video Agent to make a 30 second product explainer for a standing desk. Friendly female presenter, calm tone, vertical 9:16, clean office style. Keep checking the status until the video is ready, then give me the link."

Before rendering, ask Claude to call list_video_agent_styles. The styles are curated templates that control scene composition, pacing and look, and you can filter them by tags such as "cinematic" or "retro-tech".

Direct Avatar Videos

When the wording must be exact, such as a price list or a compliance notice, skip the agent and use create_video. A chosen avatar or a still image speaks your script or audio with lip sync. You pick Avatar III, Avatar IV or Avatar V as the engine, and Avatar IV is the default. Avatar V only works with avatars that support it.

"Use create_video with my brand avatar and this exact script. Engine Avatar V, 1080p, 16:9. Return the video_url when it is ready."

The get_video tool returns the status, video_url, thumbnail_url, duration and any failure details, so it is the one to call when a render seems stuck.

Translate With Lip Sync

Translation uses three tools: list_video_translate_languages for valid codes, create_video_translate to start the job, and get_video_translate_caption to fetch captions afterward. HeyGen offers speed and precision modes, so a quick draft and a polished final can come from the same source video. PicassoIA carries the same family as Video Translate for dubbing into 150+ languages, plus Lipsync Precision and Lipsync Speed.

Translation batches accept up to 100 items per request, which makes it realistic to localize a whole training library in one afternoon.

What the Tools Offer and Cost

Tool Groups at a Glance

Credits, Timing, and Limits

• Credits: no extra charge on top of your plan. Usage draws on your plan credits, and professional voice clones cost 1 credit per look generation.
• Filler word removal: $0.30 per source minute, with a one minute minimum.
• Timing: most renders finish in 1 to 5 minutes. Poll with exponential backoff and respect any Retry-After header.
• Rate limit: 30 requests per minute per workspace member on the professional voice synthesis endpoint.
• Batch size: 100 items per request across every batch type.
• Reference videos: up to 12 in reference to video mode, with aspect ratios from 1:4 to 4:1.
• Templates: deleting one is a soft delete, and videos already generated stay untouched.

Fix Common Problems

Symptoms and Fixes

Habits That Save Credits

• Ask Claude to restate the script, avatar and format before it renders, then reply "go".
• Test a 10 to 15 second clip before a long one.
• Fix the script first. Re-rendering over a typo burns credits for nothing.
• Run a batch only after one sample has been approved.

Where PicassoIA Fits In

HeyGen's engines are not locked inside the HeyGen app. PicassoIA lists several of them next to other talking video models, which is handy for A/B tests on the same script.

Scripts matter as much as renders. Language models on PicassoIA, such as Claude Sonnet 5, Claude Fable 5 and Claude Opus 4.7, can draft and tighten a script before it reaches any avatar tool. That gives you a clean split: write with a language model, render with an avatar model, and keep each step easy to repeat.

How to Use Avatar V on PicassoIA

The MCP route suits people who live inside Claude. If you would rather click a form, Avatar V on PicassoIA turns a typed script into a talking-head video with no camera, studio or actors.

Step by Step

1. Open the Avatar V page on PicassoIA.
2. Paste your script into input_text. The limit is under 5,000 characters per run.
3. Add a voice_id and an avatar_id. Both are required, and the avatar must support Avatar V. These IDs come from HeyGen's catalogs, and the remote connector can list voices, so Claude is a handy way to shortlist them.
4. Choose the aspect_ratio: 16:9 for widescreen or 9:16 for vertical.
5. Pick a resolution: 720p, 1080p (the default) or 4k.
6. Set voice_speed between 0.5 and 1.5, and switch caption on if you want burned-in subtitles.
7. Run the generation and download the finished file. The example run in the model gallery took about 137 seconds at 1080p.

Settings Worth Tuning

💡 Two script habits that pay off: keep sentences short enough to say in one breath, and spell out numbers and acronyms the way you want them spoken.

Try It on PicassoIA Today

You now have two routes to the same result. Connect HeyGen to Claude when you want video creation to happen inside a conversation, with one sentence kicking off a render. Use PicassoIA when you would rather pick the settings yourself and compare engines side by side.

Pick a short script you already own, maybe a product intro or a training step, and run it through Avatar V at 720p. Then send the same footage through Video Translate to hear it in a second language. Ten minutes of experimenting on PicassoIA will tell you more about your own workflow than any spec sheet. Open the platform, try a model, and build your first avatar video today.