three.ws Avatars

@three-ws/avatar-mcp

An MCP server that drops a live, rotatable 3D avatar into any chat — interactive in the conversation, embeddable anywhere. Free, no API key.

Install · Setup · Quick start · Tools · Requirements · three.ws

A thin, zero-config, read-only Model Context Protocol server that brings three.ws 3D avatars into any MCP client — Claude Desktop, Claude Code, Cursor, or any other host. Render a live, rotatable avatar inline, get a paste-anywhere embed iframe, or fetch avatar metadata. Every tool reads live from the real three.ws endpoints — no mock data. Public and unlisted avatars need no API key. Registry name: io.github.nirholas/threews-avatar. Built by three.ws.

Need wallets, voice, generation, or pump.fun powers? See the sibling package @three-ws/avatar-agent, a full 3D AI agent in a box.

Install

npm install @three-ws/avatar-mcp

Run it directly with npx (no install needed) or install globally for the avatar-mcp CLI:

npx -y @three-ws/avatar-mcp           # MCP stdio server

npm install -g @three-ws/avatar-mcp # exposes avatar-mcp

Setup

Claude Code, one line:

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

Claude Desktop / Cursor (JSON config):

{

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

No environment variables are required. To read avatars from a different host (e.g. a preview deployment), set THREEWS_BASE_URL. Restart your client after editing the config.

Inspect the tool surface in a GUI:

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

Quick start

Once connected, ask your client in plain language:

Render avatar bf58f7fc-64b3-4a92-8c27-dd472fc04b58 in the chat, dark background, auto-rotating.

(That UUID is a real public avatar. Any avatar's id is the last path segment of its three.ws URL, and GET https://three.ws/api/avatars/public lists more. A @handle works too, for any three.ws user who has published a public avatar.)

render_avatar returns three things so it looks great in every client:

1. a preview image that renders inline everywhere,
2. an interactive `text/html` resource — a real you can orbit and zoom, for hosts that render HTML resources, and
3. the embed URL + iframe to drop the live avatar into any page.

Tools

All three tools are free, read-only, and annotated (readOnlyHint, idempotentHint, openWorldHint) so hosts can run them without confirmation prompts. There is no x402 charge. Identify an avatar by `id` (UUID), `handle` (a three.ws username, with or without the @, that has a public avatar), or a raw `model` GLB URL.

Interactive 3D in the chat — the differentiator

render_avatar is an MCP App (SEP-1865): it declares a ui:// resource that supporting hosts render in a sandboxed iframe — a real, orbit-and-zoom , not a static image. The avatar is live in the conversation: rotate it, zoom it, watch it idle, without leaving the chat. Hosts without MCP Apps support still get a rendered preview image and a one-tap live embed, so the tool degrades gracefully everywhere.

Example calls

// 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" }

get_avatar on that id returns, live:

{

"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" }

Every tool also advertises an outputSchema describing its structuredContent, so typed clients can consume results without re-parsing the text blocks.

Prompts

How it works

Each selector maps to a real three.ws endpoint. Raw model URLs must be https:// (or http://localhost for dev); other schemes are rejected.

Requirements

• Node >=20.
• No credentials. Public and unlisted avatars need no API key.

Links

• Homepage: https://three.ws
• Sibling package: @three-ws/avatar-agent — full 3D AI agent (wallet, voice, pump.fun)
• Changelog: https://three.ws/changelog
• Issues: https://github.com/nirholas/three.ws/issues
• License: Apache-2.0, see LICENSE

Part of the three.ws SDK suite — 3D AI agents, on-chain identity, and agent payments.

Website · Changelog · GitHub