three.ws Avatars

@three-ws/avatar-mcp

一个 MCP 服务，可在任何聊天中放入实时、可旋转的 3D Avatar——可在对话中交互，也可嵌入到任何地方。免费，无需 API 密钥。

安装 · 设置 · 快速入门 · 工具 · 要求 · three.ws

---

一个轻量、零配置、只读的 Model Context Protocol 服务，可将 three.ws 3D Avatar 引入任何 MCP 客户端——Claude Desktop、Claude Code、Cursor 或任何其他宿主。可在聊天中渲染实时、可旋转的 Avatar，获取可粘贴到任意位置的嵌入 iframe，或获取 Avatar 元数据。每个工具都从真实的 three.ws 端点读取实时数据，不使用模拟数据。公开和未公开列出的 Avatar 均无需 API 密钥。注册表名称：io.github.nirholas/threews-avatar。由 three.ws 构建。

需要钱包、语音、生成功能或 pump.fun 能力？请查看同系列软件包 @three-ws/avatar-agent，它是一个完整的 3D AI Agent 一体化方案。

安装

npm install @three-ws/avatar-mcp

可直接使用 npx 运行（无需安装），也可全局安装以使用 avatar-mcp CLI：

npx -y @three-ws/avatar-mcp           # MCP stdio server
npm install -g @three-ws/avatar-mcp   # exposes `avatar-mcp`

设置

Claude Code，一行命令：

claude mcp add threews-avatar -- npx -y @three-ws/avatar-mcp

Claude Desktop / Cursor（JSON 配置）：

{
	"mcpServers": {
		"threews-avatar": {
			"command": "npx",
			"args": ["-y", "@three-ws/avatar-mcp"]
		}
	}
}

无需设置环境变量。如需从其他主机读取 Avatar（例如预览部署），请设置 THREEWS_BASE_URL。编辑配置后重启客户端。

在 GUI 中查看工具界面：

npx -y @modelcontextprotocol/inspector npx -y @three-ws/avatar-mcp

快速入门

连接后，用自然语言向客户端提出请求：

在聊天中渲染 Avatar bf58f7fc-64b3-4a92-8c27-dd472fc04b58，使用深色背景并自动旋转。

（该 UUID 对应一个真实的公开 Avatar。任意 Avatar 的 ID 都是其 three.ws URL 的最后一个路径段，GET https://three.ws/api/avatars/public 可列出更多 Avatar。任何发布了公开 Avatar 的 three.ws 用户也可以使用 @handle。）

render_avatar 会返回三项内容，确保在每个客户端中都能呈现出色效果：

1. 可在任何地方内嵌渲染的预览图像，
2. 可交互的 text/html 资源——一个真实的 <model-viewer>，可在支持渲染 HTML 资源的宿主中旋转和缩放，以及
3. 可将实时 Avatar 放入任何页面的嵌入 URL + iframe。

工具

这三个工具均免费、只读且带有注解（readOnlyHint、idempotentHint、openWorldHint），因此主机可以无需确认提示直接运行。不会收取 x402 费用。可通过 id（UUID）、handle（three.ws 用户名，可带或不带 @，且拥有公开头像）或原始 model GLB URL 来标识头像。

工具	选择器	功能
render_avatar	id · handle · model	内嵌渲染头像。在支持 MCP Apps 的主机上，可在聊天中直接显示可实时旋转的 3D 模型；其他客户端则会收到预览图像和嵌入 URL。参数：background（transparent/dark/light）、scene（portrait/headshot/upper-body/full-body）、auto_rotate、height（160–1080）。
avatar_embed_code	id · handle · model	返回可直接粘贴的 <iframe>，可在任何位置嵌入实时头像，简单易用，就像嵌入 YouTube 视频一样。参数：background、width（CSS）、height（160–1080）、idle（循环播放待机动画）、overlay（用于 OBS/叠加层的无边框模式）。
get_avatar	id · handle	获取头像元数据：name、GLB model_url、所有者、可见性。

聊天中的交互式 3D——差异化优势

render_avatar 是一个 MCP App（SEP-1865）：它声明了一个 ui:// 资源，支持该功能的主机会在沙盒 iframe 中渲染它——这是一个真正可旋转和缩放的 <model-viewer>，而不是静态图像。头像会实时显示在对话中：你可以旋转、缩放、观看它待机，无需离开聊天。即使主机不支持 MCP Apps，也能收到渲染后的预览图像和一键式实时嵌入，因此该工具在任何环境下都能优雅降级。

调用示例

// render_avatar — live, rotatable avatar in chat
{ "id": "bf58f7fc-64b3-4a92-8c27-dd472fc04b58", "background": "dark", "auto_rotate": true }

// avatar_embed_code — paste into any website
{ "id": "bf58f7fc-64b3-4a92-8c27-dd472fc04b58", "height": 560 }

// get_avatar: metadata, by @handle instead of id
{ "handle": "@your-handle" }

对该 id 调用 get_avatar 会实时返回：

{
	"id": "bf58f7fc-64b3-4a92-8c27-dd472fc04b58",
	"name": "Jade",
	"slug": "jade-fe1a51",
	"model_url": "https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/u/299bdfa7-d848-4865-bdb1-0db23fc3b431/jade-fe1a51.glb",
	"thumbnail": null,
	"visibility": "public"
}

每个工具还会提供描述其 structuredContent 的 outputSchema，因此类型化客户端无需重新解析文本块即可使用结果。

提示词

提示词	参数	功能
showcase-avatar	avatar — id（UUID）或 @handle	一步完成展示：在聊天中内嵌渲染可实时旋转的头像，并且生成嵌入 iframe，最后提供可复制粘贴的摘要（名称、查看器 URL、嵌入 URL、<iframe> 代码片段）。

工作原理

每个选择器都映射到一个真实的 three.ws 端点。原始 model URL 必须使用 https://（开发环境可使用 http://localhost）；其他协议都会被拒绝。

选择器 / 资源	端点
id	GET https://three.ws/api/avatars/:id
handle	GET https://three.ws/api/users/:handle/avatar
预览图片	GET https://three.ws/api/avatar/render?avatar=:id
实时嵌入	https://three.ws/avatar-embed.html?...
查看器	https://three.ws/viewer?src=:glb

要求

• Node >=20。
• 无需凭据。 公开和未列出的头像都无需 API 密钥。

变量	必填	说明
THREEWS_BASE_URL	可选	要从中读取的 three.ws 主机。默认为 https://three.ws。
THREEWS_TIMEOUT_MS	可选	每个请求的网络超时时间。默认为 30000。

链接

• 主页：https://three.ws
• 相关软件包：@three-ws/avatar-agent — 完整的 3D AI Agent（钱包、语音、pump.fun）
• 更新日志：https://three.ws/changelog
• 问题反馈：https://github.com/nirholas/three.ws/issues
• 许可证：Apache-2.0，详见 LICENSE

---

_{属于 three.ws SDK 套件的一部分 — 3D AI Agent、链上身份和 Agent 支付。
网站 · 更新日志 · GitHub}