Skip to main content
Glama

SpeechLab MCP

HappyMonkeyAI text-to-speech lab for agents, games, and video studios.

SpeechLab exposes an MCP server that can synthesize speech through local engines (Piper, Pocket TTS, Underdog Woof) and optionally Cartesia cloud voices. Clips are written as WAV files on disk; tools return absolute paths so an agent can copy them into a game or video project.

Copyright © 2026 Stephen Phillips / HappyMonkeyAI. Released under the MIT License.

Providers

Provider

Kind

Notes

piper

local

Piper HTTP (/voices, /speak)

pocket

local

Pocket TTS (POST /tts form)

woof

local

Underdog Woof (/speak) — credit Voice by Underdog Woof

cartesia

cloud

Cartesia Sonic (requires CARTESIA_API_KEY)

Miso GPU quality is planned as a later Compose profile.

Related MCP server: narration-mcp

MCP tools

Tool

Purpose

list_providers

Configured engines + health

provider_status

Detailed health for one or all

list_voices

Voice ids per provider

synthesize

text + optional provider / voice / filename_hint → { path, provider, voice, bytes, ... }

Security

  • Copy .env.example → .env locally. Never commit .env.

  • Leave CARTESIA_API_KEY empty unless you need cloud TTS.

  • Compose publishes MCP/TTS ports on loopback (127.0.0.1) by default.

  • Generated WAVs under data/out/ are gitignored.

Quick start (local stdio)

git clone https://github.com/HappyMonkeyAI/speech-lab-mcp.git
cd speech-lab-mcp
python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1
# macOS / Linux
# source .venv/bin/activate

pip install -e ".[dev]"
cp .env.example .env   # Windows: copy .env.example .env

Point provider URLs in .env at running engines, or start Compose (below), then:

speech-lab-mcp --transport stdio

Cursor mcp.json example

{
  "mcpServers": {
    "speech-lab": {
      "command": "speech-lab-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "SPEECH_LAB_OUTPUT_DIR": "/absolute/path/to/speech-lab-mcp/data/out",
        "SPEECH_LAB_PIPER_URL": "http://127.0.0.1:8090",
        "SPEECH_LAB_POCKET_URL": "http://127.0.0.1:8091",
        "CARTESIA_API_KEY": "",
        "CARTESIA_VOICE_ID": ""
      }
    }
  }
}

On Windows, command can be the full path to .venv\\Scripts\\speech-lab-mcp.exe.

Docker Compose

MCP only (Cartesia works if a key is set in the environment; local engines optional):

docker compose up --build mcp

Streamable HTTP endpoint: http://127.0.0.1:8765/mcp

Local Piper + Pocket:

docker compose --profile local up --build

Profiles:

Profile

Services

(default)

mcp

piper

Piper TTS

pocket

Pocket TTS

local

Piper + Pocket

woof

Underdog Woof (set WOOF_MODEL_DIR in .env)

Build contexts default to sibling checkouts:

  • Piper → ../text-echo/tts

  • Pocket → ../../miso/pocket

  • Woof → ../agent-voice-tts/sidecars/woof-tts

Override with PIPER_BUILD_CONTEXT, POCKET_BUILD_CONTEXT, WOOF_BUILD_CONTEXT.

WAVs are written to ./data/out on the host.

Transports

Transport

Use

stdio

Cursor / local agent subprocess

streamable-http

Compose / remote clients (/mcp)

sse

Legacy only — prefer streamable-http

Typical agent flow

  1. list_providers / provider_status — confirm a healthy engine.

  2. list_voices — pick a stable voice id per character.

  3. synthesize — generate a WAV; copy the returned path into your project assets.

  4. Keep a roster file in the consumer project so the same character always uses the same provider + voice.

Development

pip install -e ".[dev]"
pytest

Attribution

Third-party engines remain under their own licenses (Piper voices, Pocket TTS, Underdog Woof non-commercial terms, Cartesia terms of service).

Available Tools

4 tools
list_providersA

List configured TTS providers and whether each is currently healthy.

Inputs: no named parameters. Returns: result

list_voicesA

List voices for one provider, or all configured providers when omitted.

Inputs: provider. Returns: result

provider_statusB

Health-check one provider, or all configured providers when omitted.

Inputs: provider. Returns: result

synthesizeA

Synthesize speech to a WAV file and return its absolute path plus metadata.

Args: text: Spoken line to generate. provider: piper | pocket | woof | cartesia (default from env / first healthy local). voice: Provider-specific voice id or name (Pocket also accepts an audio prompt URL). filename_hint: Optional short label included in the output filename.

Inputs: text (required), voice, provider, filename_hint. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 4 tools

    Disambiguation3/5

    list_providers and provider_status overlap substantially since list_providers already reports health, making the dedicated health-check largely redundant and easy to misselect. list_voices and synthesize are clearly distinct, so the overlap is confined to two tools.

    Naming Consistency3/5

    Three tools use verb_noun (list_providers, list_voices) or bare verb (synthesize), while provider_status uses a noun_noun form, breaking the pattern. Mixed conventions but still readable.

    Tool Count4/5

    Four tools is on the lean side but appropriate for a focused TTS server: provider discovery, health, voices, and synthesis. The only inefficiency is the split between list_providers and provider_status, which could be consolidated.

    Completeness4/5

    The core TTS lifecycle (discover providers, list voices, synthesize to WAV) is well covered. Minor gaps exist around listing/managing generated audio files or configuring providers, but agents can work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers