WellSaid Claude Connector

Generate lifelike WellSaid Labs voiceover from text — right inside Claude.

This is a Model Context Protocol server that wraps the WellSaid Labs text-to-speech API and exposes it as Claude tools. Ask Claude to "list WellSaid voices" or "voice this script with Wade C., a little slower and deeper," and it renders audio (plus captions if you want them).

Runs as a local stdio connector (Claude Desktop custom connectors + Claude Code) or as a remote Streamable-HTTP connector. No build step — plain Node ESM.

---

What Claude can do with it

Tool	What it does
wellsaid_list_voices	List voice avatars and their speaker_id (name, style, accent, gender, language), with optional search.
wellsaid_list_voice_criteria	Summarize the distinct styles/accents/genders/languages to narrow a search.
wellsaid_generate_speech	Convert text → audio with a chosen voice. Supports model (legacy/caruso), AI Director prosody (pitch/tempo/loudness), output format, and replacement libraries.
wellsaid_generate_speech_with_timing	Render speech plus word timing and SRT/VTT captions — the API's zip is extracted to individual files.
wellsaid_create_clip_async	Start an async TTS job (good for long or batched scripts).
wellsaid_get_clip	Check a clip's status and download it when ready.
wellsaid_list_clips	List recent clips on the account.
wellsaid_combine_clips	Stitch multiple clips into one file with custom pauses.
wellsaid_get_respelling_suggestions	Get pronunciation respellings for a tricky name/term.
wellsaid_request	Advanced escape hatch — call any WellSaid endpoint directly.

Generated files are written to your output folder (default ./output, or set WELLSAID_OUTPUT_DIR).

Prosody & pronunciation (AI Director)

WellSaid's expressive controls run on the caruso model via AI Director tags embedded in the text. wellsaid_generate_speech exposes them two ways:

• Whole-line convenience: pass pitch, tempo, and/or loudness — the connector wraps your text in the right tags and automatically selects the caruso model. Approximate ranges: pitch [-45, 100], tempo [0.7, 2.3], loudness [-15, 9].
• Fine control: embed tags directly in text, e.g. The <emphasis>best</emphasis> value is <respell value="PEET-suh">pizza</respell>. Use wellsaid_get_respelling_suggestions to find respelling values.

Output format can be mp3 (default), wav, or s16le, with an optional sample_rate.

---

Prerequisites

• Node.js ≥ 18.17 (uses the built-in fetch). Developed on Node 24. .env auto-loads via a built-in on Node ≥ 20.12, with a manual fallback on older versions.
• A WellSaid API key — create one at wellsaidlabs.com (Studio → API) or the Developer Portal. Sent as the X-Api-Key header. Default keys are rate-limited to ~3 requests/second and 1,000 characters per synchronous request.

Install & verify

cd wellsaid-connector
npm install
cp .env.example .env        # then paste your key into WELLSAID_API_KEY
npm run doctor              # checks config + connectivity to /tts/avatars

npm run doctor prints your config and, if the key works, the number of available voices.

---

Add it to Claude

Claude Code

claude mcp add wellsaid --env WELLSAID_API_KEY=YOUR_KEY -- node /absolute/path/to/wellsaid-connector/src/index.js

Then in a session: "List my WellSaid voices" → "Generate speech for '…' with speaker_id 3, a little deeper."

Claude Desktop (config file)

Settings → Developer → Edit Config, and merge the mcpServers block from claude_desktop_config.example.json. Replace the API key, the args path, and the output dir with your own install location. Fully quit and reopen Claude Desktop; the tools then appear under the 🔌 connector menu.

Claude Desktop (one-click extension)

The repo ships a manifest.json so it can be packaged as a Desktop Extension (.mcpb) that prompts for the API key in the UI — no JSON editing:

npx @anthropic-ai/mcpb pack .      # produces wellsaid.mcpb

Drag wellsaid.mcpb into Claude Desktop → Settings → Extensions, and paste your key when prompted. The extension defaults the output folder to your Downloads folder (see the config note below).

Remote / hosted connector — public, OAuth (src/remote.js)

This is the path to a public connector anyone can add by URL. src/remote.js is an OAuth 2.1–protected MCP server (Dynamic Client Registration + PKCE) that shows a consent page where each user pastes their own WellSaid key; that key is bound to their token and used only for their requests.

npm run start:remote        # OAuth MCP server on http://localhost:8788/mcp

Deploy it to a public HTTPS URL, then in Claude → Settings → Connectors → Add custom connector → paste https://your-url/mcp. Full instructions (Docker / Render / Fly / tunnel) are in DEPLOY.md. This hosted server is also the prerequisite for a Connectors Directory submission — see PRIVACY.md for the required privacy policy template.

There's also an authless local HTTP mode for quick testing (npm run start:http, port 8787) — stateless, no auth, 4 MB body cap. Use start:remote (OAuth) for anything shared.

---

Configuration

All configuration is via environment variables (or .env):

Variable	Required	Default	Purpose
WELLSAID_API_KEY	✅	—	Your WellSaid key (X-Api-Key).
WELLSAID_API_BASE		https://api.wellsaidlabs.com/v1	Override the API base URL.
WELLSAID_OUTPUT_DIR		./output	Where audio/caption files are saved (see note).
MCP_TRANSPORT		stdio	stdio or http.
PORT		8787	Port for HTTP transport.

Output-dir note: the code default is the connector's ./output folder, used when WELLSAID_OUTPUT_DIR is unset (Claude Code / .env installs). The one-click Desktop Extension (.mcpb) and the example Claude Desktop config instead default to your ~/Downloads folder, because a packaged extension has no writable ./output. Any tool call can override with output_dir.

---

Development

npm test                     # unit + in-process + stdio + http suites
node test/unit.test.js       # client helpers, safe file writing, zip reader
node test/inmemory.test.js   # tool behavior against a mocked API (real body-building)
node test/stdio.smoke.js     # spawns the real process, exercises the MCP handshake
node test/http.smoke.js      # Streamable-HTTP transport
npm run inspect              # opens the MCP Inspector against the server

Notes on API coverage

• wellsaid_list_voices (GET /v1/tts/avatars) and wellsaid_generate_speech (POST /v1/tts/stream) are built against WellSaid's documented request/response shapes, including the integer speaker_id, model, audio_configs, and library_ids fields and inline AI Director tags.
• wellsaid_generate_speech_with_timing posts to /v1/tts/word-timing and unpacks the returned zip.
• wellsaid_combine_clips uses clip_ids + pause_durations per the combine endpoint.
• If WellSaid changes a field, wellsaid_request lets Claude call any endpoint directly while this connector is updated.

Security

• Your API key stays in your local environment / MCP client config; it is only sent to api.wellsaidlabs.com (or your WELLSAID_API_BASE) as X-Api-Key, and is never logged or written to disk.
• Output filenames are reduced to a bare basename, so a tool call can never write outside your configured output folder.

License

MIT