Realtime Avatar

realtime-avatar-mcp

在 npm 上发布为 realtime-avatar-mcp —— 使用 npx 运行，无需安装到应用中。

一个用于 Realtime Avatar 的 MCP 服务。AGENTS.md 会告诉编码 Agent API 的相关信息；这个服务能让它查看你的虚拟形象、余额和账单，而不是猜测 ID、编造数据结构。

{
  "mcpServers": {
    "realtime-avatar": {
      "command": "npx",
      "args": ["-y", "realtime-avatar-mcp"],
      "env": { "REALTIME_AVATAR_API_KEY": "tic_test_…" }
    }
  }
}

完整页面包含写入工具及其费用： https://realtimeavatar.ai/docs/mcp。你需要先获取 API 密钥——沙盒密钥 免费且无需绑定银行卡。

在此仓库中开发？运行 npm run build，然后将 command 指向 node，并设置 args: ["/abs/path/to/realtime-avatar-sdk/libs/mcp/dist/bin.js"]。

工具

工具
list_avatars	列出所有可传递给 startCall 的虚拟形象 ID，以及哪些可用于实时通话
get_avatar	查看单个虚拟形象的完整详情
credit_balance	查看余额，以及进行中通话预留的额度
list_sessions	查看明细账单——每个会话的运行时间、时长和费用
list_clips	查看虚拟形象的片段库：所有片段及其状态、版本和静止姿势

设置 REALTIME_AVATAR_ALLOW_WRITES=1 后：

工具		计费？
set_loop	根据新描述重新指定她的待机循环	否
set_clip_library	以 JSON 声明虚拟形象的完整片段集——由平台进行渲染	否
upload_asset	从本机磁盘上传文件，并获取公开 URL	否
create_remote_asset	注册已在互联网上的文件——无需本地副本	否
create_avatar_from_image	从一张静态图片创建虚拟形象——循环由系统生成	否
create_avatar_from_video	已弃用。 不再接受新的调用方（422）。请使用图片工具	否
start_call	创建实时会话以验证集成	按秒计费

消费费用需主动启用，并经过双重门控

上述五个工具均为只读，每个工具都带有 readOnlyHint，因此宿主可以根据该注解进行门控，而无需识别工具名称。即使使用生产密钥，此服务的危险程度也不超过一个未关闭的控制面板。

设置 REALTIME_AVATAR_ALLOW_WRITES=1 可启用写入工具。只有 start_call 会消耗额度，而且它会直接拒绝 tic_live_ 密钥——操作员若针对测试密钥启用了写入功能，之后又换成生产密钥，不应因此意外产生费用。设置两道独立门控，是因为只靠一道门控，出错一次就形同虚设。

启用写入功能前，有两点需要了解：

• **upload_asset 会读取本地磁盘。**它会打开 Agent 指定的任意绝对路径，路径位于运行此服务的机器上。相对路径会被拒绝，不会根据宿主启动服务时所在的目录进行解析。
• 片段声明中未包含的片段会被移除。set_clip_library 接收的是完整集合；任何未列出的片段都将停止提供服务。其计划会报告保留、排队和移除的片段。请声明 source.motionPrompt 或 source.assetId；媒体由平台托管并进行准备。虚拟形象存储的源是默认静止状态——无需声明，因此 ID primary 为保留值。

为什么要使用 MCP 服务

即使 Agent 会阅读文档，也仍然会猜测。无法推断出 ava_… ID，而且最耗时的故障在类型签名中不可见：浏览器客户端会拒绝重塑后的连接负载；通话返回 429 表示请求正在排队，并非错误；待机循环来自虚拟形象的源，而不是片段库，因此任何声明都不会改变它。

list_avatars 会标记哪些虚拟形象确实可用。服务的 instructions 中包含中继规则和按秒计费模式。这些上下文是 Agent 无法自行推导的，并会在它即将采取行动时提供。