three.ws Avatars — Claude Code MCP server: setup and usage
Brings interactive 3D models into chat windows and generates iframe embed snippets. Works out of the box with zero API keys required for public assets.
claude mcp add --env THREEWS_BASE_URL=<THREEWS_BASE_URL> --transport stdio threews-avatar-mcp -- npx -y @three-ws/avatar-mcpWhat three.ws Avatars does
This read-only MCP server links your assistant to three.ws endpoints. If the host platform supports MCP Apps, users can orbit and inspect rotatable 3D characters right inside the conversation via <model-viewer>. Standard hosts receive a rendered image preview alongside a shareable embed URL.
The server packages three tools: render_avatar, avatar_embed_code, and get_avatar. You identify avatars through a UUID, a user handle, or a direct GLB asset URL. The embed helper produces an <iframe> snippet with configurable height, background, and idle animations.
Public models need no API key. All requests hit live three.ws endpoints without mock data. If you connect to a custom staging host, pass the THREEWS_BASE_URL environment variable.
What it helps with
- display interactive 3D models inside agent conversations
- generate clean
<iframe>embed codes for websites - fetch GLB file URLs and owner details for an avatar
- adjust scene framing and background style for 3D previews
Example prompts for the agent
- Render user handle @alex with a dark background and auto rotation enabled.
- Create an iframe embed code for avatar bf58f7fc-64b3-4a92-8c27-dd472fc04b58 with a height of 500px.
- Fetch the GLB file URL and metadata for avatar bf58f7fc-64b3-4a92-8c27-dd472fc04b58.
How to install three.ws Avatars
Platform CLI
claude mcp add --env THREEWS_BASE_URL=<THREEWS_BASE_URL> --transport stdio threews-avatar-mcp -- npx -y @three-ws/avatar-mcpReplace <…> with your own values
Platform CLI
codex mcp add threews-avatar-mcp --env THREEWS_BASE_URL=<THREEWS_BASE_URL> -- npx -y @three-ws/avatar-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"threews-avatar-mcp": {
"command": "npx",
"args": [
"-y",
"@three-ws/avatar-mcp"
],
"env": {
"THREEWS_BASE_URL": "<THREEWS_BASE_URL>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"threews-avatar-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@three-ws/avatar-mcp"
],
"env": {
"THREEWS_BASE_URL": "<THREEWS_BASE_URL>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e THREEWS_BASE_URL=<THREEWS_BASE_URL> threews-avatar-mcp npx -y @three-ws/avatar-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about three.ws Avatars
How do I install three.ws Avatars in Claude Code?
Run claude mcp add threews-avatar -- npx -y @three-ws/avatar-mcp in your terminal.
Does three.ws Avatars require an API key?
No, all public and unlisted avatars work immediately without an API key or account token.
How does render_avatar display 3D models in chat?
On MCP Apps hosts it renders an interactive <model-viewer> iframe, while other clients receive a static preview image and embed link.
