three.ws Avatars

@three-ws/avatar-mcp

あらゆるチャットに、回転操作できるライブ3Dアバターを表示するMCPサーバーです。会話内で操作でき、どこにでも埋め込めます。無料で、APIキーは不要です。

インストール · セットアップ · クイックスタート · ツール · 必要条件 · three.ws

---

three.wsの3Dアバターを、Claude Desktop、Claude Code、Cursorなど、あらゆるホストのMCPクライアントで利用できるようにする、シンプルで設定不要の読み取り専用Model Context Protocolサーバーです。回転操作できるライブアバターをインラインで表示したり、どこにでも貼り付けられる埋め込みiframeを取得したり、アバターのメタデータを取得したりできます。すべてのツールは実際のthree.wsエンドポイントから最新のデータを取得し、モックデータは使用しません。公開アバターと限定公開アバターにはAPIキーは不要です。レジストリ名：io.github.nirholas/threews-avatar。three.wsが開発しました。

ウォレット、音声、生成、pump.funの機能が必要ですか？姉妹パッケージの@three-ws/avatar-agentをご覧ください。3D AIエージェントをすぐに使える形で提供します。

インストール

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の場合は、次の1行を実行します。

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

環境変数は不要です。別のホスト（プレビュー環境など）からアバターを読み込むには、THREEWS_BASE_URLを設定してください。設定を編集したら、クライアントを再起動してください。

GUIでツールの構成を確認するには、次を実行します。

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

クイックスタート

接続したら、クライアントに自然な言葉で依頼します。

アバターbf58f7fc-64b3-4a92-8c27-dd472fc04b58をチャットに表示して。背景は暗く、自動回転で。

（このUUIDは実在する公開アバターです。アバターのIDはthree.wsのURLの最後のパス要素です。また、GET https://three.ws/api/avatars/publicでほかのアバターを確認できます。公開アバターを公開しているthree.wsユーザーであれば、@handleも使えます。）

render_avatarは、あらゆるクライアントで見栄えよく表示できるよう、次の3つを返します。

1. どこでもインライン表示できるプレビュー画像、
2. 実際の<model-viewer>を使用したインタラクティブなtext/htmlリソース（HTMLリソースを表示できるホストでは、回転やズームができます）、および
3. ライブアバターを任意のページに埋め込むための埋め込みURLとiframe。

ツール

3 つのツールはいずれも無料で、読み取り専用であり、注釈（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）であり、対応ホストがサンドボックス化された iframe 内でレンダリングする ui:// リソースを宣言します。静止画像ではなく、実際に回転やズームができる <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 エージェント（ウォレット、音声、pump.fun）
• 変更履歴：https://three.ws/changelog
• イシュー：https://github.com/nirholas/three.ws/issues
• ライセンス：Apache-2.0。詳細は LICENSE をご覧ください。

---

_{three.ws SDK スイートの一部です — 3D AI エージェント、オンチェーン ID、エージェント決済。
ウェブサイト · 変更履歴 · GitHub}