3D AI Agent Avatar

io.github.nirholasPublished by GitHub account nirholasv1.2.3Updated Oct 24, 2026

3D AI Agent Avatar — render any GLB, give it a Solana wallet, a voice, and pump.fun powers.

VerifiedSTDIODesktop onlyFinanceMedia & DesignAI & ML

Overview

AI-generated overview

Local MCP server that inspects, validates and optimizes GLB models, spawns 3D avatars with voice, and runs Solana wallet and pump.fun operations.

What you can do
  • Inspect, validate, optimize and thumbnail any GLB model, and build three.ws viewer URLs or iframes
  • List, spawn, dress and render avatars, and generate new 3D avatars from text or images via Replicate
  • Synthesize speech in the avatar's voice through NVIDIA or OpenAI TTS
  • Create Solana wallets with optional vanity prefixes, read balances, preview and send SOL
  • Snapshot pump.fun markets, quote and execute Jupiter buys, launch tokens and collect creator fees
  • Resolve .eth and .sol names to addresses
When to use it
Useful when you want an assistant to check or shrink 3D assets, produce avatar renders and voice clips, or manage Solana wallets and pump.fun trades from chat. The 3D tools and market snapshots work without any keys, so it is also worth adding just for GLB inspection.
Requirements
Node.js 20 or newer; runs locally via npx over stdio. No keys needed for the 3D tools and pump_snapshot. Optional keys: NVIDIA_API_KEY and OPENAI_API_KEY for speech, REPLICATE_API_TOKEN for avatar generation, HELIUS_API_KEY for enhanced snapshots, SOLANA_SECRET_KEY for signing, ETH_RPC_URL for .eth lookups. SOLANA_RPC_URL defaults to a public mainnet endpoint.
Before you install
Four tools (wallet_send, pump_buy, pump_launch, pump_collect_fees) sign and broadcast real mainnet transactions that move real funds. SOLANA_SECRET_KEY and secrets returned by wallet_create are spendable funds; treat them like cash. The server executes what it is told, so keep REQUIRE_CONFIRM on, set MAX_SOL_PER_TX and RECIPIENT_ALLOWLIST, and review previews first. Model URLs, thumbnails and renders go to the hosted three.ws service, and generation goes to Replicate.

Installation

In SourceWeft

  1. Open 3D AI Agent Avatar in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[three.ws]

@three-ws/avatar-agent

An MCP server that turns any GLB into a 3D AI agent — inspect/validate/optimize models, then give one a Solana wallet, a voice, and pump.fun powers.

[npm] [downloads] [license] [node] [mcp] [MCP Registry]

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

A single Model Context Protocol server that is two things at once. It is a general-purpose 3D toolkit — inspect_glb, validate_glb, optimize_glb, thumbnail_glb, and viewer_url work on any GLB/glTF model, no avatar required, powered by @gltf-transform/core and Khronos's official gltf-validator. It is also a 3D AI agent in a box — spawn a textured GLB avatar, give it a voice (OpenAI TTS), hand it a Solana wallet, and run pump.fun operations (Jupiter swaps, atomic Jito-bundled launches, creator-fee collection). Built and maintained by three.ws. Registry name: io.github.nirholas/3D-AI-Agent-Avatar.

For a lightweight, read-only avatar viewer (no wallet, no signing), see the sibling package @three-ws/avatar-mcp, which renders a live, rotatable on-chain avatar inline in the chat.

Install

bash
npm install @three-ws/avatar-agent

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

bash
npx -y @three-ws/avatar-agent          # MCP stdio servernpm install -g @three-ws/avatar-agent  # exposes `three-avatar-agent`

Setup

Add the server to your MCP client. Claude Code, one line:

bash
claude mcp add avatar-agent -- npx -y @three-ws/avatar-agent

Claude Desktop / Cursor (JSON config):

json
{	"mcpServers": {		"avatar-agent": {			"command": "npx",			"args": ["-y", "@three-ws/avatar-agent"],			"env": {				"SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com",				"OPENAI_API_KEY": "sk-...",				"REPLICATE_API_TOKEN": "r8_..."			}		}	}}

The 3D tools (inspect_glb, validate_glb, optimize_glb, thumbnail_glb, viewer_url) and pump_snapshot work with no environment variables. Voice, generation, and signing tools need the keys in Requirements. Restart your client after editing the config.

Inspect the full tool surface in a GUI:

bash
npx -y @modelcontextprotocol/inspector npx -y @three-ws/avatar-agent

Quick start

Once connected, ask your client in plain language:

Inspect https://three.ws/avatars/cz.glb — how many triangles? Then validate it against the Khronos spec and optimize it with Draco.

Runs inspect_glb → validate_glb → optimize_glb({ draco: true }), returning the rewritten GLB inline with honest before/after sizes. Note that cz.glb already ships EXT_meshopt_compression + WebP textures, so re-encoding it with Draco reports a negative savedBytes: the pipeline never hides that, and an uncompressed source is where the wins actually are.

Spawn the cz avatar, give him shades, mint him a three-prefixed Solana wallet, pull a snapshot of $THREE, and have him say "we're so back."

Runs spawn_avatar → dress_avatar → wallet_create({ vanityPrefix: "three" }) → pump_snapshot → speak.

Tools

All 24 tools are free MCP tools: there is no per-call x402 charge. Tools marked execution sign and broadcast real Solana transactions that move real funds; configure your client's tool-approval flow for them.

Every tool ships MCP tool annotations: reads advertise readOnlyHint: true, and the four execution tools (wallet_send, pump_buy, pump_launch, pump_collect_fees) are flagged destructiveHint: true, so annotation-aware MCP clients prompt for confirmation before running them. The hints are advisory — the server-side REQUIRE_CONFIRM gate and spend caps (see Safety) apply regardless of client.

3D toolkit — works on any GLB, no avatar required

ToolWhat it does
inspect_glbMesh / material / texture / animation / skin breakdown, bounding box, vertex and triangle counts. @gltf-transform/core.
validate_glbRuns Khronos's official gltf-validator; returns errors, warnings, infos, hints with JSON pointers.
optimize_glbDedup → prune → weld → optional Draco. Returns the rewritten bytes inline with before/after sizes and a signed savedBytes (negative when re-encoding an already-compressed model costs more than it saves). Draco- and meshopt-compressed inputs are decoded on read, so a compressed avatar works like any other.
thumbnail_glbRenders any GLB to a PNG via three.ws's hosted three-light rig + auto-framing camera. Returns base64 PNG inline.
viewer_urlBuilds a three.ws/viewer?... URL + paste-ready iframe for any GLB or avatar session (background, auto-rotate, camera preset or explicit orbit, AR mode, dimensions).

Avatar

ToolWhat it does
list_avatarsCatalog of default GLB avatars (default, cz), accessories, and pose presets.
list_animationsLive fetch of three.ws's pose presets (T-pose, wave, thinker, jump, dance, warrior2, …) grouped by category.
spawn_avatarCreates an avatar session from a preset or custom GLB URL. Returns a sessionId.
dress_avatarApplies accessories + a pose to a session.
render_avatarRenders a posed avatar to a PNG — pose preset + camera orbit (theta/phi/radius) + ARKit-52 facial expression.
generate_avatarText/image-to-3D via Replicate (Hunyuan-3D). New session preloaded with the generated GLB.

Voice

ToolWhat it does
speakSynthesizes speech in the avatar's voice — free NVIDIA Magpie TTS lane first (NVIDIA_API_KEY), OpenAI TTS backstop (OPENAI_API_KEY). Returns base64 audio the client plays.

Wallet

ToolWhat it does
wallet_createGenerates a Solana keypair. Optional vanity grinder (vanityPrefix: "three"). Secret is returned once.
wallet_balanceReads SOL + all SPL token balances (incl. Token-2022).
wallet_send_previewPreviews a wallet_send: sender, recipient, amount, network fee, balance before and after, and any rule that would refuse it. Signs nothing.
wallet_sendSends SOL on mainnet. Execution.

pump.fun

ToolWhat it does
pump_snapshotLive market snapshot: USD price (Jupiter), 24h volume + DEX (Dexscreener), pump.fun metadata, top-holder distribution. Pass target: "three" for $THREE when THREE_MINT is set. Read-only, no signer.
pump_buy_quoteQuotes a pump_buy for the exact amount and slippage: SOL spent, expected and minimum tokens, price impact, route and fees. Signs nothing; pass its quote_id to pump_buy.
pump_buyJupiter swap, direct or Jito-bundled (funder→buyer transfer + swap atomic). Accepts any runtime mint. Execution.
pump_launch_previewPreviews a pump_launch: funder and creator addresses, rent, dev buy, bundle tip, the funder's total and any rule that would refuse it. Signs, uploads and mints nothing.
pump_launchAtomic launch via Jito bundle: separate funder + creator wallets, both txs in the same block. Uploads metadata to pump.fun IPFS if no URI is supplied. Execution.
pump_collect_previewPreviews pump_collect_fees: the live fee vault balance, rent kept behind, the exact SOL that would reach the destination, and any rule that would refuse it. Signs nothing.
pump_collect_feesAtomic collect: collectCoinCreatorFee + drain to a safe wallet in one tx inside a Jito bundle — resistant to a leaked creator key. Execution.

Identity

ToolWhat it does
ens_sns_resolveResolves .eth (ENS) and .sol (SNS) names to addresses, with reverse + favorite-domain lookups. SNS is read straight from the SPL Name Service accounts on your SOLANA_RPC_URL, so it depends on no third-party name service.

How atomic pump.fun works

The pump_launch and pump_collect_fees tools wrap two patterns:

  • Launch — the create tx's payerKey is the creator wallet, so the on-chain creator field (which receives pump.fun creator fees forever) is the creator wallet. The creator does not need to hold SOL: the funder transfers rent + tip in Tx1 of the same Jito bundle. Either both txs land or neither does.
  • Collect — even if a creator key is shared or leaked, collect-and-drain runs as a single tx inside a Jito bundle, so no competing collector can interleave a tx between collectCoinCreatorFee and the drain.

If you start hitting Bundles must write lock at least one tip account, the Jito tip-account list has rotated.

These tools accept an arbitrary mint supplied at runtime — generic plumbing for launching and managing your own coin. $THREE (FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump) is the only coin three.ws promotes.

Requirements

  • Node >=20.

Per-tool environment variables (all optional — set only what you use):

VariableRequired forNotes
SOLANA_RPC_URLAll Solana opsDefaults to https://api.mainnet-beta.solana.com. Bring your own (Helius / Quicknode / Triton) for production traffic.
ETH_RPC_URLens_sns_resolve (.eth lane)Strongly recommended. Without it ethers falls back to its shared community endpoints, which are throttled hard enough that .eth lookups routinely time out. .sol needs nothing here. Alias: MAINNET_RPC_URL.
HELIUS_API_KEYpump_snapshot (enhanced)Adds exact supply + DAS data.
NVIDIA_API_KEYspeak (free lane)NVIDIA NIM key (nvapi-…) — leads the TTS provider chain with Magpie TTS.
OPENAI_API_KEYspeak (paid backstop)Used against api.openai.com/v1/audio/speech when the free lane is unavailable.
REPLICATE_API_TOKENgenerate_avatarReplicate text/image-to-3D.
REPLICATE_TEXT_TO_AVATAR_MODELgenerate_avatarPin a commercial-OK version, e.g. latest tencent/hunyuan-3d-3.1.
SOLANA_SECRET_KEYwallet_send / pump_buy default signerPer-call secret args override. Alias: FUNDER_SECRET. Treat like cash.
THREE_MINTpump_snapshot / pump_buy shorthandSet so tools accept target: "three". Defaults to the canonical $THREE mint.
MAX_SOL_PER_TXexecution toolsPer-transaction spend cap in SOL. Default 0.5.
REQUIRE_CONFIRMexecution toolsDefault on: execution calls refuse until re-issued with confirm: true. Set 0/false to disable.
RECIPIENT_ALLOWLISTexecution toolsOptional comma-separated base58 pubkeys. When set, SOL destinations (wallet_send, the pump_collect_fees drain target) must be in the list.
NAME_RESOLVE_TIMEOUT_MSens_sns_resolveBudget for one lane of a name lookup. Default 15000. Raise it when pointing at a slow self-hosted RPC.
VIEWER_BASEviewer_urlDefaults to https://three.ws/viewer. Override to point links at a self-hosted viewer.
THREE_WS_BASEhosted rendering / animation catalogDefaults to https://three.ws. Override only when self-hosting the three.ws backend.

Safety

wallet_send, pump_buy, pump_launch, and pump_collect_fees execute real on-chain transactions. The server makes no judgment about inputs — with a valid signer it does exactly what it is told. Secrets are never logged or persisted; the secret from wallet_create is returned once.

Four layers keep that power in check:

  1. Tool annotations — the four execution tools are flagged destructiveHint: true, so annotation-aware MCP clients (Claude Code, Claude Desktop, Cursor) surface a confirmation prompt before running them. Read-only tools are flagged readOnlyHint: true and can be safely auto-approved.
  2. Confirmation gate — with REQUIRE_CONFIRM on (the default), every execution call returns confirmation_required until re-issued with confirm: true, independent of the client.
  3. Spend caps — MAX_SOL_PER_TX (default 0.5 SOL) bounds every send, buy, tip, and drain server-side. Enforced in the signing libs themselves, so every path — direct, bundled, atomic — is covered.
  4. Recipient allowlist — set RECIPIENT_ALLOWLIST and any SOL destination outside the list is refused before a transaction is built.

Errors

A failed tool call returns an MCP error result (isError: true) whose text is a single JSON object — { "ok": false, "error": "<code>", "message": "…" }, plus status or the on-chain signature when available:

errorMeaningRecovery
confirmation_requiredAn execution tool was called without confirm: true while REQUIRE_CONFIRM is on. Returned as a normal (non-error) result — a deliberate refusal, not a failure.Re-issue the same call with confirm: true.
over_spend_capThe requested SOL amount exceeds MAX_SOL_PER_TX.Lower the amount, or raise MAX_SOL_PER_TX in the server env (you accept the risk).
recipient_not_allowedRECIPIENT_ALLOWLIST is set and the destination isn't in it.Send to an allowlisted address or extend the list.
invalid_amountA zero, negative, or non-numeric SOL amount.Pass a positive number.
vault_too_small / nothing_to_drainpump_collect_fees found no (or dust-level) creator fees to collect.Nothing to do — check back after more trading volume.
simulation_failedThe transaction failed Solana preflight simulation; nothing was broadcast.The message carries the program logs — fix the underlying cause and retry.
bad_rpc_url / insecure_rpc_urlSOLANA_RPC_URL is malformed or plain-http on a non-localhost host.Use an https:// RPC endpoint (or http://localhost for a local validator).
bad_policy_configMAX_SOL_PER_TX (or another policy var) is not a non-negative number.Fix the env var value.

Execution errors that occur after broadcast include the transaction signature so you can verify the final on-chain state before retrying — never assume a failed response means no funds moved.

Links

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

Source: packages/avatar-agent-mcp/README.md at commit 0e68f46

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v1.2.3LatestOct 10, 2026
  2. v1.2.2Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts