three.ws Audio

io.github.nirholasPublished by GitHub account nirholasv0.1.3Updated Oct 24, 2026

Text-to-speech, speech-to-text, audio-to-face lipsync, and motion-capture clips for 3D agents.

VerifiedSTDIODesktop onlyMedia & DesignAI & ML

Overview

AI-generated overview

A local stdio MCP server that gives an assistant text-to-speech, speech-to-text, audio-to-face lipsync and motion-capture clip browsing for 3D agents.

What you can do
Synthesize spoken audio from text, returning a base64 audio data URL with voice and format details, using free NVIDIA models with an OpenAI backstop option. Transcribe base64 audio into text with confidence and duration. Turn text or audio into a per-frame ARKit blendshape lipsync track, optionally together with generated audio. Browse the motion-capture clip library by kind with cursor pagination, and fetch a single clip's full per-frame animation track by id.
When to use it
Useful when building or driving a 3D avatar or agent that needs a voice, speech input, mouth animation, or recorded face, pose, hand and VMC motion data, from any MCP client such as Claude Code, Claude Desktop or Cursor.
Requirements
Runs locally over stdio via npx, requiring Node.js 20 or newer and network access to the three.ws API. Optional environment variables: THREE_WS_BASE to point at another deployment, THREE_WS_API_KEY for higher rate limits and private clips, and THREE_WS_TIMEOUT_MS for per-request timeouts. No key is needed to start.
Before you install
Audio and text are sent to the three.ws service and its upstream model providers for synthesis, recognition and lipsync. THREE_WS_API_KEY is a bearer token that raises metered rate limits, so usage may be billed; the OpenAI TTS backstop is described as paid. Recognition input is capped around 8 MB, and browser-recorded WebM/Opus must be converted to WAV or PCM first.

Installation

In SourceWeft

  1. Open three.ws Audio 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/audio-mcp

Give a 3D AI agent a voice and a face — text-to-speech, speech-to-text, audio-to-face lipsync, and the motion-capture clip library, from any MCP client.

[npm] [license] [node] [MCP Registry] [three.ws]

A Model Context Protocol server that exposes the three.ws voice and animation pipeline over stdio. Make an avatar speak, let users talk back, turn that speech into a per-frame lipsync track, and browse the recorded motion-capture library — everything you need to drive a 3D agent's mouth and movement.

The speech, recognition, and lipsync lanes run on free NVIDIA NIM models (Magpie TTS, Riva ASR, Audio2Face-3D), with OpenAI as the paid TTS backstop — the same provider policy as the three.ws platform. No key required to start; point THREE_WS_BASE at a deployment and go.

Install

bash
npm install @three-ws/audio-mcp

Or run with npx (no install):

bash
npx @three-ws/audio-mcp

Quick start

Claude Code, one line:

bash
claude mcp add audio -- npx -y @three-ws/audio-mcp

Claude Desktop / Cursor (claude_desktop_config.json or mcp.json):

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

Inspect the surface with the MCP Inspector:

bash
npx -y @modelcontextprotocol/inspector npx @three-ws/audio-mcp

Tools

ToolTypeWhat it does
text_to_speechread-onlySynthesize spoken audio from text; returns a base64 audio data URL plus the real voice/format/mime. Free Magpie, OpenAI backstop.
speech_to_textread-onlyTranscribe spoken audio (base64 wav/pcm/flac/ogg) with the free NVIDIA Riva recognizer; returns text, confidence, duration.
audio_to_faceread-onlyTurn speech (text you pass, or audio you have) into a per-frame ARKit blendshape lipsync track via Audio2Face-3D.
motion_capture_clipsread-onlyBrowse the motion-capture clip library — recorded face/pose/hand/VMC tracks — with kind filter and cursor pagination.
motion_capture_clipread-onlyFetch one clip by id including its full per-frame animation track to play back on an avatar.

All five tools are read-only: they transform input (synthesize/recognize/animate) or read live library data, never mutating platform state. None are idempotent — the audio bytes, transcript, and catalog move between calls.

Input parameters

text_to_speech — text (required, 1–4096 chars), voice (default nova), format (mp3|opus|aac|flac|wav|pcm, default mp3), model (OpenAI backstop only), language (BCP-47, default en-US), speed (0.5–2.0, OpenAI lane only).

speech_to_text — audio (required, base64 or data: URL), format (wav|pcm|flac|ogg, default wav), language (BCP-47, default en-US), sampleRate (Hz, PCM only), words (bool), model (advanced).

audio_to_face — text or audio (one required), format (wav|pcm, audio path), sampleRate (PCM only), voice / language (text path).

motion_capture_clips — kind (face|pose|hand|vmc), include_public (bool, authenticated only), limit (1–100, default 50), cursor.

motion_capture_clip — id (required, clip UUID).

Examples

jsonc
// text_to_speech> { "text": "Hello, I'm your three.ws agent.", "voice": "nova" }{  "ok": true,  "voice": "Magpie-Multilingual.EN-US.Aria",  "model": "magpie-tts-multilingual",  "format": "wav",  "mime": "audio/wav",  "sizeBytes": 274476,  "audio": "data:audio/wav;base64,UklGR…"}
jsonc
// audio_to_face (text path — returns audio + the lipsync track together)> { "text": "Watch my lips move." }{  "ok": true,  "audio": { "base64": "UklGR…", "contentType": "audio/wav", "format": "wav" },  "animation": {    "fps": 30,    "blendShapeNames": ["jawOpen", "mouthClose", "…"],    "durationSec": 1.9,    "frames": [ { "t": 0.0, "w": [0.0, 0.1, /* … */] } ]  }}

A face frame is { t, w }: t = seconds from clip start, w = weights in the order of blendShapeNames (ARKit-52 naming). Play the audio and sample the track by the audio element's currentTime.

Notes on payloads

Audio crosses the wire as base64 (TTS returns it, ASR/A2F accept it). Both the synthesis input (text) and the recognition input (audio, ~8 MB cap) are bounded by the platform — keep clips to a spoken utterance rather than long recordings. For lipsync on audio you already have, pass wav/pcm directly; browser-recorded WebM/Opus must be decoded to WAV or PCM first (Riva and Audio2Face do not accept the WebM container).

Requirements

  • Node.js >= 20.
  • Network access to https://three.ws (or your own THREE_WS_BASE).

Environment variables

VariableRequiredDefaultPurpose
THREE_WS_BASEnohttps://three.wsWhich deployment to talk to.
THREE_WS_API_KEYno—Bearer token. Raises the metered TTS/ASR/A2F rate limits and unlocks your own private mocap clips.
THREE_WS_TIMEOUT_MSno60000Per-request timeout for the live model calls.

Links

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

Source: packages/audio-mcp/README.md at commit c8f2cde

Tools

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

Version history

2
  1. v0.1.3LatestOct 10, 2026
  2. v0.1.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