voice-soundboard 2.5.2

Text-to-speech for AI agents and developers. Compiler → Graph → Engine architecture.

日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

48 voices • 9 languages • 5 presets • 8 emotions • SSML-lite • SFX tags • multi-speaker dialogue
Swappable TTS backends. Guardrails built in. Ships as a single npx command.

---

Highlights

• MCP native — stdio transport, works with Claude Desktop, Cursor, and any MCP client
• 5 tools — voice_speak, voice_dialogue, voice_status, voice_interrupt, voice_inner_monologue
• 48 approved voices, 9 languages — English (American + British), Japanese, Mandarin, Spanish, French, Hindi, Italian, Brazilian Portuguese. Curated presets: narrator, announcer, whisper, storyteller, assistant
• Emotion spans — 8 emotions via {joy}...{/joy} inline markup
• SSML-lite — <break>, <emphasis>, <prosody> without full SSML complexity
• SFX tags — [ding], [chime], [whoosh], [tada], [pop], [click] inline sound effects
• Multi-speaker dialogue — Speaker: line format with auto-cast and pause directives
• Guardrails — rate limiting, concurrency semaphore, request timeouts, path traversal protection, secret redaction
• Swappable backends — Mock (built-in), HTTP proxy, Python bridge, or bring your own

Quick Start

npx @mcptoolshop/voice-soundboard-mcp

Or install globally:

npm install -g @mcptoolshop/voice-soundboard-mcp
voice-soundboard-mcp

Claude Desktop / MCP Client Config

Add to your MCP client configuration (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "voice-soundboard": {
      "command": "npx",
      "args": ["-y", "@mcptoolshop/voice-soundboard-mcp"]
    }
  }
}

With options:

{
  "mcpServers": {
    "voice-soundboard": {
      "command": "npx",
      "args": [
        "-y", "@mcptoolshop/voice-soundboard-mcp",
        "--artifact=path",
        "--output-dir=/tmp/voice-output",
        "--timeout=30000",
        "--max-concurrent=2"
      ]
    }
  }
}

MCP Tools

voice_speak

Synthesize speech from text.

text:         "Hello world!"
voice?:       "am_fenrir"          # Voice ID or preset name
speed?:       1.0                  # 0.5 - 2.0
mood?:        "dry"                # Humor mood (sensor-humor integration)
format?:      "wav"                # wav | mp3 | ogg | raw
artifactMode?: "path"             # path | base64
outputDir?:   "subdir"            # Subdirectory within output root
sfx?:         true                # Enable [ding], [chime] etc.

voice_dialogue

Multi-speaker dialogue synthesis.

script:       "Alice: Hello!\nBob: Hey there!"
cast?:        { "Alice": "af_sky", "Bob": "am_fenrir" }
speed?:       1.0
concat?:      true                 # Combine into single file
debug?:       true                 # Include cue_sheet
artifactMode?: "path"             # path | base64
outputDir?:   "subdir"            # Subdirectory within output root

voice_status

Returns engine health, available voices, presets, and backend info. No arguments.

voice_interrupt

Stop or rollback active synthesis.

streamId?:    "stream-123"
reason?:      "user_spoke"         # user_spoke | context_change | timeout | manual

voice_inner_monologue

Ephemeral micro-utterances for ambient narration. Requires --ambient flag or VOICE_SOUNDBOARD_AMBIENT_ENABLED=1.

text:         "Interesting..."     # Max 500 chars, auto-redacted
category?:    "thinking"           # general | thinking | observation | debug

Voices

48 voices across 9 languages. Language is auto-inferred from the voice ID prefix — no configuration required.

Prefix	Language
af_ / am_	English (American)
bf_ / bm_	English (British)
jf_ / jm_	Japanese
zf_ / zm_	Mandarin Chinese
ef_ / em_	Spanish
ff_	French
hf_ / hm_	Hindi
if_ / im_	Italian
pf_ / pm_	Brazilian Portuguese

English — American

ID	Name	Gender	Style
af_aoede	Aoede	Female	Musical
af_bella	Bella	Female	Warm
af_heart	Heart	Female	Caring
af_jessica	Jessica	Female	Professional
af_kore	Kore	Female	Youthful
af_nicole	Nicole	Female	Soft
af_sarah	Sarah	Female	Clear
af_sky	Sky	Female	Airy
am_eric	Eric	Male	Confident
am_fenrir	Fenrir	Male	Powerful
am_liam	Liam	Male	Friendly
am_michael	Michael	Male	Deep
am_onyx	Onyx	Male	Smooth
am_puck	Puck	Male	Playful

English — British

ID	Name	Gender	Style
bf_alice	Alice	Female	Proper
bf_emma	Emma	Female	Refined
bf_isabella	Isabella	Female	Warm
bm_fable	Fable	Male	Storytelling
bm_george	George	Male	Authoritative
bm_lewis	Lewis	Male	Friendly

Japanese

ID	Name	Gender	Style
jf_alpha	Alpha	Female	Clear
jf_gongitsune	Gongitsune	Female	Storytelling
jf_nezuko	Nezuko	Female	Gentle
jf_tebukuro	Tebukuro	Female	Warm
jm_kumo	Kumo	Male	Calm

Mandarin Chinese

ID	Name	Gender	Style
zf_xiaobei	Xiaobei	Female	Bright
zf_xiaoni	Xiaoni	Female	Gentle
zf_xiaoxiao	Xiaoxiao	Female	Clear
zf_xiaoyi	Xiaoyi	Female	Warm
zm_yunjian	Yunjian	Male	Authoritative
zm_yunxi	Yunxi	Male	Friendly
zm_yunxia	Yunxia	Male	Calm
zm_yunyang	Yunyang	Male	Confident

Spanish

ID	Name	Gender	Style
ef_dora	Dora	Female	Warm
em_alex	Alex	Male	Confident
em_santa	Santa	Male	Jolly

French

ID	Name	Gender	Style
ff_siwis	Siwis	Female	Refined

Hindi

ID	Name	Gender	Style
hf_alpha	Alpha	Female	Clear
hf_beta	Beta	Female	Warm
hm_omega	Omega	Male	Deep
hm_psi	Psi	Male	Calm

Italian

ID	Name	Gender	Style
if_sara	Sara	Female	Warm
im_nicola	Nicola	Male	Confident

Brazilian Portuguese

ID	Name	Gender	Style
pf_dora	Dora	Female	Warm
pm_alex	Alex	Male	Confident
pm_santa	Santa	Male	Jolly

Presets

Preset	Voice	Speed	Description
narrator	bm_george	0.95	Calm, clear, documentary style
announcer	am_eric	1.1	Bold, energetic, broadcast style
whisper	af_sky	0.85	Soft, intimate, gentle
storyteller	bf_emma	0.90	Expressive, varied pacing
assistant	af_jessica	1.0	Friendly, helpful, conversational

Emotion Spans

Wrap text in emotion tags to control prosody and voice routing:

{joy}Great news!{/joy} But {calm}let me explain.{/calm}

Supported: neutral, serious, friendly, professional, calm, joy, urgent, whisper

CLI Flags

Flag	Default	Description
--artifact=path|base64	path	Audio delivery mode
--output-dir=<path>	<tmpdir>/voice-soundboard/	Output directory
--backend=mock|http|python	mock	Backend selection
--ambient	off	Enable inner-monologue system
--max-concurrent=<n>	3	Max concurrent synthesis requests
--timeout=<ms>	60000	Per-request timeout
--retention-minutes=<n>	240	Auto-cleanup age (0 to disable)

Packages

This is a pnpm monorepo with two publishable packages:

Package	Description	npm
@mcptoolshop/voice-soundboard-core	Backend-agnostic core library (validation, SSML, chunking, schemas)
@mcptoolshop/voice-soundboard-mcp	MCP server with CLI, guardrails, and transport

Development

# Install
pnpm install

# Build
pnpm build

# Test (363 tests)
pnpm test

# Build + test in one step
pnpm verify

Part of MCP Tool Shop

Project Structure

mcp-voice-soundboard/
  packages/
    core/               @mcptoolshop/voice-soundboard-core
      src/
        limits.ts         SHIP_LIMITS, text/chunk limits
        schemas.ts        VoiceRequest, VoiceResponse, error codes
        artifact.ts       resolveOutputDir, path sandbox
        voices.ts         Approved voice registry + presets
        emotion.ts        Emotion span parser
        ssml/             SSML-lite parser + limits
        chunking/         Text chunker
        sfx/              SFX tag parser + registry
        sandbox.ts        Safe filenames, symlink checks
        ambient.ts        AmbientEmitter for inner monologue
        redact.ts         PII/secret redaction
    mcp-server/         @mcptoolshop/voice-soundboard-mcp
      src/
        server.ts         MCP tool registration + guardrail wiring
        cli.ts            CLI entrypoint (stdio transport)
        backend.ts        Backend abstraction + mock/HTTP
        concurrency.ts    SynthesisSemaphore
        rateLimit.ts      ToolRateLimiter (sliding window)
        timeout.ts        withTimeout utility
        retention.ts      Output file cleanup timer
        redact.ts         Server-level redaction
        validation.ts     Synthesis result validation
        tools/            Individual tool handlers
  assets/               Logo, audio event manifests
  docs/                 Architecture docs

Privacy

No telemetry. This tool collects no usage data, sends no analytics, and makes no network requests except to the TTS backend you configure. All processing is local.

Security

See SECURITY.md for vulnerability reporting.

See THREAT_MODEL.md for the full threat surface analysis.

Related

Project	Description
soundboard-plugin	Claude Code plugin — slash commands, emotion-aware narration

Support

• Questions / help: Discussions
• Bug reports: Issues
• Security: SECURITY.md

Scorecard

Category	Score	Notes
A. Security	10/10	SECURITY.md, THREAT_MODEL.md, redaction, no telemetry
B. Error Handling	8/10	Structured error contract (code/hint/retryable), toToolError pattern
C. Operator Docs	9/10	README, CHANGELOG, HANDBOOK, tool docs
D. Shipping Hygiene	9/10	CI, verify script, dependabot, lockfile
E. Identity	10/10	Logo, translations, landing page, metadata
Total	46/50

License

MIT

---

Built by MCP Tool Shop