尧图网站建设 
Klavis HeyGen MCP Server为 AI Agent 接入数字人视频生成与语音合成能力【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavisHeyGen MCP Server 是 Klavis 仓库中基于 Model Context ProtocolMCP实现的 HeyGen 集成服务它把 HeyGen 的数字人视频生成、语音合成、数字人资产管理等 API 能力封装成标准的 MCP 工具让 Claude、Cursor、VS Code 等任意 MCP 客户端都能直接调用。读完本文你将掌握该服务在托管与自托管两种模式下的快速接入方法、全部 10 个工具的调用参数与底层端点映射以及从 HTTP 客户端到双传输协议SSE / StreamableHTTP的完整源码实现原理。项目定位把 HeyGen API 变成 AI Agent 的数字人工具箱Klavis 将 HeyGen MCP Server 定位为Create AI-generated videos and avatars using HeyGens API——即通过标准 MCP 协议把 HeyGen 的 API 能力抽象为一组可供 AI Agent 直接调用的工具函数。Agent 不再需要自己拼接 REST 请求而是通过list_tools/call_tool协议完成能力发现与调用实现让 AI 自动生成带数字人讲解的视频这类端到端任务。整个服务是一个纯 Python 实现代码结构非常清晰位于 mcp_servers/heygenserver.py服务入口负责注册工具清单、路由分发、API Key 提取与双传输协议SSE、StreamableHTTP装配tools/按职责拆分的五个工具模块base、account、assets、generation、management对应 README 中提到的五大能力类别Video Generation视频生成数字人视频创建与渲染状态查询Avatar Management数字人管理数字人模板与分组的查询Voice Synthesis语音合成AI 音色与语言locale资源查询Template Operations模板操作数字人分组资源的管理Rendering Control渲染控制视频渲染与处理状态监控。快速开始托管与自托管两种接入路径方式一Klavis 托管服务生产环境推荐README 推荐生产环境使用 Klavis 托管基础设施无需自行搭建只需获取 API Key 后安装官方 SDKpip install klavis # 或 npm install klavisPython 侧创建一个 HeyGen MCP Server 实例只需两行代码from klavis import Klavis klavis Klavis(api_keyyour-free-key) server klavis.mcp_server.create_server_instance(HEYGEN, user123)若使用 Strata 托管模式仓库文档 docs/mcp-server/heygen.mdx 给出了更完整的接入流程先通过klavis_client.mcp_server.create_strata_server(servers[McpServerName.HEYGEN], user_iduser123)创建 Strata 服务器再用set_strata_auth写入 HeyGen 的 API Token 完成认证from klavis import Klavis from klavis.types import McpServerName klavis_client Klavis(api_keyYOUR_API_KEY) # 创建包含 HeyGen 的 Strata MCP 服务器 response klavis_client.mcp_server.create_strata_server( servers[McpServerName.HEYGEN], user_iduser123 ) # 写入 HeyGen API Key 完成认证 klavis_client.mcp_server.set_strata_auth( strata_idresponse.strata_id, server_nameMcpServerName.HEYGEN, auth_data{ token: YOUR_HEYGEN_API_KEY } )其中userIduser123用于标识访问的是哪个用户/团队/组织的已连接账户与数据应使用你自己的唯一标识。认证完成后拿到的 MCP Server URL 即可接入任意 MCP 兼容客户端。同样操作也可在 Klavis 控制台Dashboard中以 UI 方式完成选择 HeyGen 集成 → 填入 HeyGen API Key → 复制 MCP 端点 URL 配置到客户端。方式二Docker 自托管从源码自托管时直接拉取官方镜像并注入 HeyGen API Key# 拉取最新镜像 docker pull ghcr.io/klavis-ai/heygen-mcp-server:latest # 运行 HeyGen MCP Server docker run -p 5000:5000 -e API_KEY$API_KEY \ ghcr.io/klavis-ai/heygen-mcp-server:latestAPI_KEY即你在 [HeyGen Dashboard]HeyGen 官方控制台申请的 HeyGen API Key仓库文档 docs/mcp-server/heygen.mdx 的自托管变体则使用KLAVIS_API_KEY环境变量两种变量名分别对应直接注入 HeyGen Key与通过 Klavis 平台鉴权两种方式按你的部署场景二选一。若要在本地从源码构建并运行可进入 mcp_servers/heygen 目录安装 requirements.txt 中的依赖后执行python server.py具体依赖版本见下文配置与依赖一节。构建镜像的 Dockerfile 基于python:3.12-slim仅拷贝server.py与tools/目录EXPOSE 5000暴露默认端口。从源码结构观察Dockerfile 中COPY mcp_servers/hubspot/requirements.txt .一行沿用了 hubspot 服务的依赖清单路径自托管构建时如遇依赖缺失可将其替换为mcp_servers/heygen/requirements.txt。工具全景10 个 HeyGen MCP 工具的调用参数在 server.py 的list_tools中注册了 10 个工具按ToolAnnotations的category分为四类HEYGEN_ACCOUNT、HEYGEN_VOICE、HEYGEN_AVATAR、HEYGEN_VIDEO并标注了readOnlyHint 区分只读与写操作工具名分类功能必填参数可选参数与默认值heygen_get_remaining_credits账户查询账户剩余额度无—heygen_get_voices语音查询可用音色列表无limit默认 20最大 100heygen_get_voice_locales语音查询可用语言locale列表无limit默认 20heygen_get_avatar_groups数字人查询数字人分组无—heygen_get_avatars_in_avatar_group数字人查询分组内数字人group_id—heygen_list_avatars数字人列出全部数字人含 Instant 与公共数字人无limit默认 20heygen_generate_avatar_video视频生成数字人讲解视频avatar_id、text≤1500 字符、voice_idbackground_color默认#ffffff、width默认 1280、height默认 720、avatar_style默认normalheygen_get_avatar_video_status视频查询视频渲染状态video_id—heygen_list_videos视频列出账户内视频无limit默认 20offset默认 0heygen_delete_video视频删除账户内视频video_id—工具调用结果统一以json.dumps(result, indent2)格式的TextContent返回参数缺失或 API 异常时返回带Error:前缀的文本方便 Agent 与开发者直接排查。典型调用链数字人视频生成生成视频是核心写操作其输入约束与请求体结构在 tools/generation.py 中定义text超过 1500 字符会直接抛出ValueError请求体把video_inputs中的charactertype: avataravatar_idavatar_style、voicetype: textinput_textvoice_id、backgroundtype: color 十六进制色值以及dimension宽高组合为一次 POST 请求。配合只读工具Agent 的完整工作流是heygen_list_avatars选数字人 →heygen_get_voices选音色 →heygen_generate_avatar_video提交任务 →heygen_get_avatar_video_status轮询渲染状态 →heygen_list_videos确认结果 → 必要时heygen_delete_video清理。源码解析工具层如何与 HeyGen API 通信统一的异步 HTTP 客户端tools/base.py所有工具最终都收敛到 tools/base.py 中的make_request这是理解整个服务底层行为的关键API 基地址HEYGEN_API_ENDPOINT https://api.heygen.com认证方式get_headers()返回X-Api-Key: token请求头配合Content-Type: application/json与Accept: application/json。Token 的解析优先级为请求级auth_token_contextContextVar→ 环境变量HEYGEN_API_KEY两者皆无则抛出RuntimeError(No HeyGen API key found in context or environment)请求超时httpx.AsyncClient(timeout60.0)单次调用最长等待 60 秒错误处理HTTPStatusError会尝试解析响应体中的message/error字段包装为HeyGen API error (status_code): detail其他异常包装为HeyGen API request failed: detail空响应兼容204 No Content或空响应体统一返回{success: True}删除类操作常见。各模块的端点映射每个工具模块对应一组固定的 HeyGen REST 端点相对路径tools/account.pyGET /v2/user/remaining_quota查询剩余额度并把返回的quota除以 60 换算成credits字段quota ÷ 60 credits后写入响应tools/assets.pyGET /v2/voices、GET /v2/voices/locales、GET /v2/avatar_group.list、GET /v2/avatar_groups/{group_id}/avatars、GET /v2/avatars。为避免 MCP 上下文溢出列表类结果会按limit截断并附加note字段提示Showing first N of M ...heygen_list_avatars还会无条件移除响应中的talking_photos数组以压缩体积tools/generation.pyPOST /v2/video/generate创建视频任务、GET /v1/video_status.get以video_id为查询参数轮询状态tools/management.pyGET /v1/video.list携带limit/offset分页参数、DELETE /v1/video.delete携带video_id。服务端入口双传输协议与鉴权server.pyserver.py 使用mcp.server.lowlevel.Server构建核心并同时挂载两种传输StreamableHTTPMount(/mcp, ...)由StreamableHTTPSessionManager管理statelessTrue无状态模式支持--json-response切换为 JSON 响应而非 SSE 流SSERoute(/sse, ...)GETMount(/messages/, ...)POST 消息回传。启动时日志会打印两个端点地址http://localhost:5000/sse与http://localhost:5000/mcp。MCP 客户端配置如 Claude Desktop 等通常使用 StreamableHTTP 端点{ mcpServers: { heygen: { url: http://localhost:5000/mcp/ } } }鉴权层面extract_api_key优先读取环境变量API_KEY若未设置则解析请求头x-auth-data——这是一个 Base64 编码的 JSON取其中的token或api_key字段。提取到的 token 通过auth_token_context.set()写入 ContextVar在请求生命周期内供工具层读取SSE 请求对象与 StreamableHTTP 的 scope 字典分别做了兼容处理请求结束后在finally中 reset避免跨请求串号。配置与依赖环境变量、CLI 参数与运行前提环境变量API_KEY服务级 HeyGen API KeyDocker 注入方式见 server.pyHEYGEN_API_KEY工具层兜底读取的 HeyGen Keytools/base.pyHEYGEN_MCP_SERVER_PORT默认端口未设置时取5000int(os.getenv(HEYGEN_MCP_SERVER_PORT, 5000))。CLI 参数python server.py启动时通过 click 提供--portHTTP 监听端口默认取HEYGEN_MCP_SERVER_PORT环境变量--log-level日志级别可选DEBUG / INFO / WARNING / ERROR / CRITICAL默认INFO--json-response布尔开关开启后 StreamableHTTP 返回 JSON 响应而非 SSE 流。依赖清单requirements.txtclick8.0.0、httpx0.25.0、mcp1.11.0MCP 协议实现、python-dotenv1.0.0自动加载.env、starlette0.49.1与uvicorn0.24.0ASGI 服务。服务启动时会调用load_dotenv()加载本地.env文件。需要说明的适用前提以上端点与参数均以当前仓库源码为准HeyGen 官方 API 的配额、可用音色/数字人集合以及视频渲染耗时取决于你的 HeyGen 账户权益与任务复杂度服务本身不承诺具体性能。扩展与协作在 Klavis 托管生态中HeyGen 工具默认全部开放可通过 Klavis 的get_toolsAPI 做渐进式能力发现项目采用 Apache 2.0 开源协议详见仓库根目录 LICENSE贡献指南见 CONTRIBUTING.md若需在本地二次开发建议从 tools/ 各模块入手新增工具只需在对应模块实现一个调用make_request的异步函数并在 server.py 的list_tools与call_tool中同步注册即可服务会自动将其暴露给所有 MCP 客户端。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Klavis HeyGen MCP Server：为 AI Agent 接入数字人视频生成与语音合成能力
Klavis HeyGen MCP Server为 AI Agent 接入数字人视频生成与语音合成能力【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavisHeyGen MCP Server 是 Klavis 仓库中基于 Model Context ProtocolMCP实现的 HeyGen 集成服务它把 HeyGen 的数字人视频生成、语音合成、数字人资产管理等 API 能力封装成标准的 MCP 工具让 Claude、Cursor、VS Code 等任意 MCP 客户端都能直接调用。读完本文你将掌握该服务在托管与自托管两种模式下的快速接入方法、全部 10 个工具的调用参数与底层端点映射以及从 HTTP 客户端到双传输协议SSE / StreamableHTTP的完整源码实现原理。项目定位把 HeyGen API 变成 AI Agent 的数字人工具箱Klavis 将 HeyGen MCP Server 定位为Create AI-generated videos and avatars using HeyGens API——即通过标准 MCP 协议把 HeyGen 的 API 能力抽象为一组可供 AI Agent 直接调用的工具函数。Agent 不再需要自己拼接 REST 请求而是通过list_tools/call_tool协议完成能力发现与调用实现让 AI 自动生成带数字人讲解的视频这类端到端任务。整个服务是一个纯 Python 实现代码结构非常清晰位于 mcp_servers/heygenserver.py服务入口负责注册工具清单、路由分发、API Key 提取与双传输协议SSE、StreamableHTTP装配tools/按职责拆分的五个工具模块base、account、assets、generation、management对应 README 中提到的五大能力类别Video Generation视频生成数字人视频创建与渲染状态查询Avatar Management数字人管理数字人模板与分组的查询Voice Synthesis语音合成AI 音色与语言locale资源查询Template Operations模板操作数字人分组资源的管理Rendering Control渲染控制视频渲染与处理状态监控。快速开始托管与自托管两种接入路径方式一Klavis 托管服务生产环境推荐README 推荐生产环境使用 Klavis 托管基础设施无需自行搭建只需获取 API Key 后安装官方 SDKpip install klavis # 或 npm install klavisPython 侧创建一个 HeyGen MCP Server 实例只需两行代码from klavis import Klavis klavis Klavis(api_keyyour-free-key) server klavis.mcp_server.create_server_instance(HEYGEN, user123)若使用 Strata 托管模式仓库文档 docs/mcp-server/heygen.mdx 给出了更完整的接入流程先通过klavis_client.mcp_server.create_strata_server(servers[McpServerName.HEYGEN], user_iduser123)创建 Strata 服务器再用set_strata_auth写入 HeyGen 的 API Token 完成认证from klavis import Klavis from klavis.types import McpServerName klavis_client Klavis(api_keyYOUR_API_KEY) # 创建包含 HeyGen 的 Strata MCP 服务器 response klavis_client.mcp_server.create_strata_server( servers[McpServerName.HEYGEN], user_iduser123 ) # 写入 HeyGen API Key 完成认证 klavis_client.mcp_server.set_strata_auth( strata_idresponse.strata_id, server_nameMcpServerName.HEYGEN, auth_data{ token: YOUR_HEYGEN_API_KEY } )其中userIduser123用于标识访问的是哪个用户/团队/组织的已连接账户与数据应使用你自己的唯一标识。认证完成后拿到的 MCP Server URL 即可接入任意 MCP 兼容客户端。同样操作也可在 Klavis 控制台Dashboard中以 UI 方式完成选择 HeyGen 集成 → 填入 HeyGen API Key → 复制 MCP 端点 URL 配置到客户端。方式二Docker 自托管从源码自托管时直接拉取官方镜像并注入 HeyGen API Key# 拉取最新镜像 docker pull ghcr.io/klavis-ai/heygen-mcp-server:latest # 运行 HeyGen MCP Server docker run -p 5000:5000 -e API_KEY$API_KEY \ ghcr.io/klavis-ai/heygen-mcp-server:latestAPI_KEY即你在 [HeyGen Dashboard]HeyGen 官方控制台申请的 HeyGen API Key仓库文档 docs/mcp-server/heygen.mdx 的自托管变体则使用KLAVIS_API_KEY环境变量两种变量名分别对应直接注入 HeyGen Key与通过 Klavis 平台鉴权两种方式按你的部署场景二选一。若要在本地从源码构建并运行可进入 mcp_servers/heygen 目录安装 requirements.txt 中的依赖后执行python server.py具体依赖版本见下文配置与依赖一节。构建镜像的 Dockerfile 基于python:3.12-slim仅拷贝server.py与tools/目录EXPOSE 5000暴露默认端口。从源码结构观察Dockerfile 中COPY mcp_servers/hubspot/requirements.txt .一行沿用了 hubspot 服务的依赖清单路径自托管构建时如遇依赖缺失可将其替换为mcp_servers/heygen/requirements.txt。工具全景10 个 HeyGen MCP 工具的调用参数在 server.py 的list_tools中注册了 10 个工具按ToolAnnotations的category分为四类HEYGEN_ACCOUNT、HEYGEN_VOICE、HEYGEN_AVATAR、HEYGEN_VIDEO并标注了readOnlyHint 区分只读与写操作工具名分类功能必填参数可选参数与默认值heygen_get_remaining_credits账户查询账户剩余额度无—heygen_get_voices语音查询可用音色列表无limit默认 20最大 100heygen_get_voice_locales语音查询可用语言locale列表无limit默认 20heygen_get_avatar_groups数字人查询数字人分组无—heygen_get_avatars_in_avatar_group数字人查询分组内数字人group_id—heygen_list_avatars数字人列出全部数字人含 Instant 与公共数字人无limit默认 20heygen_generate_avatar_video视频生成数字人讲解视频avatar_id、text≤1500 字符、voice_idbackground_color默认#ffffff、width默认 1280、height默认 720、avatar_style默认normalheygen_get_avatar_video_status视频查询视频渲染状态video_id—heygen_list_videos视频列出账户内视频无limit默认 20offset默认 0heygen_delete_video视频删除账户内视频video_id—工具调用结果统一以json.dumps(result, indent2)格式的TextContent返回参数缺失或 API 异常时返回带Error:前缀的文本方便 Agent 与开发者直接排查。典型调用链数字人视频生成生成视频是核心写操作其输入约束与请求体结构在 tools/generation.py 中定义text超过 1500 字符会直接抛出ValueError请求体把video_inputs中的charactertype: avataravatar_idavatar_style、voicetype: textinput_textvoice_id、backgroundtype: color 十六进制色值以及dimension宽高组合为一次 POST 请求。配合只读工具Agent 的完整工作流是heygen_list_avatars选数字人 →heygen_get_voices选音色 →heygen_generate_avatar_video提交任务 →heygen_get_avatar_video_status轮询渲染状态 →heygen_list_videos确认结果 → 必要时heygen_delete_video清理。源码解析工具层如何与 HeyGen API 通信统一的异步 HTTP 客户端tools/base.py所有工具最终都收敛到 tools/base.py 中的make_request这是理解整个服务底层行为的关键API 基地址HEYGEN_API_ENDPOINT https://api.heygen.com认证方式get_headers()返回X-Api-Key: token请求头配合Content-Type: application/json与Accept: application/json。Token 的解析优先级为请求级auth_token_contextContextVar→ 环境变量HEYGEN_API_KEY两者皆无则抛出RuntimeError(No HeyGen API key found in context or environment)请求超时httpx.AsyncClient(timeout60.0)单次调用最长等待 60 秒错误处理HTTPStatusError会尝试解析响应体中的message/error字段包装为HeyGen API error (status_code): detail其他异常包装为HeyGen API request failed: detail空响应兼容204 No Content或空响应体统一返回{success: True}删除类操作常见。各模块的端点映射每个工具模块对应一组固定的 HeyGen REST 端点相对路径tools/account.pyGET /v2/user/remaining_quota查询剩余额度并把返回的quota除以 60 换算成credits字段quota ÷ 60 credits后写入响应tools/assets.pyGET /v2/voices、GET /v2/voices/locales、GET /v2/avatar_group.list、GET /v2/avatar_groups/{group_id}/avatars、GET /v2/avatars。为避免 MCP 上下文溢出列表类结果会按limit截断并附加note字段提示Showing first N of M ...heygen_list_avatars还会无条件移除响应中的talking_photos数组以压缩体积tools/generation.pyPOST /v2/video/generate创建视频任务、GET /v1/video_status.get以video_id为查询参数轮询状态tools/management.pyGET /v1/video.list携带limit/offset分页参数、DELETE /v1/video.delete携带video_id。服务端入口双传输协议与鉴权server.pyserver.py 使用mcp.server.lowlevel.Server构建核心并同时挂载两种传输StreamableHTTPMount(/mcp, ...)由StreamableHTTPSessionManager管理statelessTrue无状态模式支持--json-response切换为 JSON 响应而非 SSE 流SSERoute(/sse, ...)GETMount(/messages/, ...)POST 消息回传。启动时日志会打印两个端点地址http://localhost:5000/sse与http://localhost:5000/mcp。MCP 客户端配置如 Claude Desktop 等通常使用 StreamableHTTP 端点{ mcpServers: { heygen: { url: http://localhost:5000/mcp/ } } }鉴权层面extract_api_key优先读取环境变量API_KEY若未设置则解析请求头x-auth-data——这是一个 Base64 编码的 JSON取其中的token或api_key字段。提取到的 token 通过auth_token_context.set()写入 ContextVar在请求生命周期内供工具层读取SSE 请求对象与 StreamableHTTP 的 scope 字典分别做了兼容处理请求结束后在finally中 reset避免跨请求串号。配置与依赖环境变量、CLI 参数与运行前提环境变量API_KEY服务级 HeyGen API KeyDocker 注入方式见 server.pyHEYGEN_API_KEY工具层兜底读取的 HeyGen Keytools/base.pyHEYGEN_MCP_SERVER_PORT默认端口未设置时取5000int(os.getenv(HEYGEN_MCP_SERVER_PORT, 5000))。CLI 参数python server.py启动时通过 click 提供--portHTTP 监听端口默认取HEYGEN_MCP_SERVER_PORT环境变量--log-level日志级别可选DEBUG / INFO / WARNING / ERROR / CRITICAL默认INFO--json-response布尔开关开启后 StreamableHTTP 返回 JSON 响应而非 SSE 流。依赖清单requirements.txtclick8.0.0、httpx0.25.0、mcp1.11.0MCP 协议实现、python-dotenv1.0.0自动加载.env、starlette0.49.1与uvicorn0.24.0ASGI 服务。服务启动时会调用load_dotenv()加载本地.env文件。需要说明的适用前提以上端点与参数均以当前仓库源码为准HeyGen 官方 API 的配额、可用音色/数字人集合以及视频渲染耗时取决于你的 HeyGen 账户权益与任务复杂度服务本身不承诺具体性能。扩展与协作在 Klavis 托管生态中HeyGen 工具默认全部开放可通过 Klavis 的get_toolsAPI 做渐进式能力发现项目采用 Apache 2.0 开源协议详见仓库根目录 LICENSE贡献指南见 CONTRIBUTING.md若需在本地二次开发建议从 tools/ 各模块入手新增工具只需在对应模块实现一个调用make_request的异步函数并在 server.py 的list_tools与call_tool中同步注册即可服务会自动将其暴露给所有 MCP 客户端。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考