Text-to-Speech MCP Server

An MCP server that exposes a text-to-speech tool, powered by the free, no-API-key gTTS library (which wraps Google Translate's internal TTS endpoint).

• Free — no API key, no billing, no GCP account.

• Many languages — English, Bengali, Spanish, and ~60 more.

• File output — saves an MP3 and returns its path.

• Resilient — retries transient/rate-limit failures with exponential backoff.

Note: gTTS uses an undocumented Google endpoint. It requires internet access and can rate-limit or change without notice — great for personal/internal use, less suited to high-volume production. The engine is isolated in engine.py so it can be swapped for Google Cloud TTS or an offline engine later.

Requirements

• uv

• Python 3.12 (uv will provision it)

Related MCP server: MCP Audio Server

Setup

uv sync

This creates .venv/ and installs the project (and its deps: gtts, mcp).

Optional configuration — copy .env.example to .env and edit:

Run

uv run tts-server
# or
uv run python -m tts_server.server

The server speaks MCP over stdio.

Tools

text_to_speech

Returns: Saved <N> KB MP3 to <path>, or Error: <reason>.

list_languages

No arguments. Returns supported code: name pairs.

Install in an MCP client

This is a standard stdio MCP server, so it works with any MCP-compatible client (Claude Code, Claude Desktop, Cursor, Windsurf, Continue, etc.). Every client needs the same three things:

Replace <ABS_PROJECT_PATH> with the absolute path to this project. Using uv --directory <path> run means the client can launch the server from anywhere and still resolve the right virtual env and .env. Make sure uv is on the client's PATH (or use the absolute path to the uv binary — find it with which uv).

Claude Code (CLI)

# user scope = available in every project; use --scope project for just this repo
claude mcp add text-to-speech --scope user -- \
  uv --directory /abs/path/to/text-to-speech-agent run tts-server

Verify, inspect, or remove:

claude mcp list                 # health check
claude mcp get text-to-speech   # show config
claude mcp remove text-to-speech

Tools load when a session starts, so open a new session after adding.

Claude Desktop

Edit the config file (Settings → Developer → Edit Config, or directly):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add (see claude_desktop_config.example.json):

{
  "mcpServers": {
    "text-to-speech": {
      "command": "uv",
      "args": ["--directory", "/abs/path/to/text-to-speech-agent", "run", "tts-server"],
      "env": { "TTS_OUTPUT_DIR": "/abs/path/to/text-to-speech-agent/output" }
    }
  }
}

Then fully restart Claude Desktop.

Cursor / Windsurf / other JSON-config clients

These use the same mcpServers JSON shape as Claude Desktop. Add the block above to the client's MCP config (e.g. Cursor: Settings → MCP, or ~/.cursor/mcp.json), then reload the client.

Generic stdio client

Any client that can launch a stdio server: configure it to run

uv --directory /abs/path/to/text-to-speech-agent run tts-server

and (optionally) pass environment variables from the table in Setup.

Troubleshooting

• Server fails to start / "uv not found" — use the absolute path to uv (which uv) as the command, since GUI clients often don't inherit your shell PATH.

• Tools don't appear — restart the client (Claude Code: start a new session).

• MP3s land in the wrong place — set TTS_OUTPUT_DIR in the client's env block (it overrides .env).

• Synthesis errors — gTTS needs internet and may rate-limit; the server retries automatically, but check connectivity if it persists.

Project layout

src/tts_server/
  server.py   # MCP tools, validation, response shaping
  engine.py   # gTTS wrapper + retry/backoff (only file importing gTTS)
  config.py   # env-driven settings
  utils.py    # filename gen, language validation, file sizing
tests/        # unit tests (retry paths, mocked gTTS)
output/       # generated MP3s

Tests

uv run python -m pytest -q