@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.

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

npm install @three-ws/avatar-agent

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

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

#Setup

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

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

Claude Desktop / Cursor (JSON config):

{
	"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:

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

#Avatar

#Voice

#Wallet

#pump.fun

#Identity

#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):

#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:

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

• Homepage: https://three.ws
• Sibling package: @three-ws/avatar-mcp — live, read-only avatar viewer for MCP
• 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}