Skip to main content
Glama
README.md
# telnyx-mcp

A private MCP server that gives an assistant Telnyx **text-to-speech**: find a voice,
synthesise text into an MP3 file, render a whole script with timed pauses, and price a
job before running it.

## Einrichten — ein Eintrag, kein Clone

`npx` holt das Paket direkt aus GitHub. Kein Clone, kein Docker, kein Build. Das hier
ist der komplette Vorgang:

```json
{
  "mcpServers": {
    "telnyx": {
      "command": "npx",
      "args": ["-y", "git+ssh://git@github.com/m8rzel/telnyx-mcp.git"],
      "env": {
        "TELNYX_API_KEY": "<dein-key>",
        "TELNYX_TTS_OUTPUT_DIR": "/Users/marcel/mcp/telnyx-audio"
      }
    }
  }
}
```

Für Claude Code als Einzeiler:

```bash
mkdir -p ~/mcp/telnyx-audio
claude mcp add telnyx -s user \
  -e TELNYX_API_KEY=dein-key \
  -e TELNYX_TTS_OUTPUT_DIR="$HOME/mcp/telnyx-audio" \
  -- npx -y git+ssh://git@github.com/m8rzel/telnyx-mcp.git
```

`TELNYX_TTS_OUTPUT_DIR` muss ein **existierender absoluter Pfad** sein. Die Werkzeuge
geben den *Pfad* der erzeugten MP3 zurück, nie die Audiodaten — ein relativer Pfad oder
ein Ordner, den es nicht gibt, liefert dem Client eine Dateiangabe, mit der er nichts
anfangen kann. Lässt du die Variable weg, landen die Dateien in
`<os-temp>/telnyx-mcp` und werden vom System irgendwann aufgeräumt.

`-y` unterdrückt die Rückfrage „Ok to proceed?“ — ohne das Flag würde `npx` beim ersten
Start auf eine Eingabe warten, die ein MCP-Client nie gibt, und in einen Timeout laufen.

### Zugang zum privaten Repo

Das Repository ist privat, also braucht `npx` Credentials für den Clone. Es gibt zwei
saubere Wege und eine Notlösung:

| Weg | Spec in `args` | Haken |
| --- | --- | --- |
| **SSH** (empfohlen) | `git+ssh://git@github.com/m8rzel/telnyx-mcp.git` | Braucht einen entsperrten Schlüssel im `ssh-agent`. Hat der Schlüssel eine Passphrase und erreicht der MCP-Client den Agent nicht, scheitert der Clone — Lösung unten. |
| **HTTPS + Keychain** | `git+https://github.com/m8rzel/telnyx-mcp.git` | Funktioniert nur, wenn `git` den macOS-Keychain-Helper benutzt und dort ein Token für github.com liegt. Läuft das Token ab, bricht der Start ohne sichtbaren Grund ab. |
| **PAT in der URL** | `git+https://<token>@github.com/m8rzel/telnyx-mcp.git` | **Nicht benutzen.** Das Token steht im Klartext in der MCP-Config, wird mitgesichert, mitgesynct und landet in jedem Screenshot der Datei. Nur als Notlösung, wenn beides andere ausfällt — und danach das Token rotieren. |

**SSH einrichten (einmalig, macOS).** Der Punkt ist, dass der MCP-Client als
GUI-Kindprozess startet und nicht die Shell-Umgebung erbt, in der dein `ssh-agent`
läuft. Mit dem Schlüssel in der Keychain übernimmt der systemweite Agent das:

```bash
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
```

und in `~/.ssh/config`:

```
Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519
```

`UseKeychain yes` lässt `ssh` die Passphrase aus der Keychain holen, statt interaktiv zu
fragen — genau der Fall, in dem ein Kindprozess ohne Terminal sonst hängen bleibt.
Prüfen mit `ssh -T git@github.com` (muss ohne Passphrase-Prompt durchlaufen) und danach
mit dem echten Aufruf:

```bash
TELNYX_API_KEY=dein-key TELNYX_TTS_OUTPUT_DIR="$HOME/mcp/telnyx-audio" \
  npx -y git+ssh://git@github.com/m8rzel/telnyx-mcp.git
```

`telnyx-mcp ready. Output directory: …` auf stderr heißt: läuft. Strg-C beendet.

**HTTPS einrichten.** Zuerst nachsehen, was `git` als Credential-Helper benutzt:

```bash
git config --get credential.helper        # erwartet: osxkeychain
git credential-osxkeychain                # muss existieren (Hinweistext = vorhanden)
```

Steht dort nichts oder etwas anderes, einmal setzen und ein Token hinterlegen:

```bash
git config --global credential.helper osxkeychain
git clone https://github.com/m8rzel/telnyx-mcp.git /tmp/telnyx-auth-test
```

Beim Clone fragt `git` nach Benutzer und Passwort; als Passwort ein Personal Access
Token mit `repo`-Scope eingeben (nicht das GitHub-Passwort). Es liegt danach in der
Keychain, und `npx` kommt ohne weitere Eingabe durch. Das Testverzeichnis kannst du
wieder löschen. Prüfen, dass es sitzt: `git ls-remote https://github.com/m8rzel/telnyx-mcp.git`
läuft ohne Rückfrage durch.

Die Haken dieses Wegs: Das Token hat ein Ablaufdatum, und wenn es abläuft, startet der
Server ohne erkennbaren Zusammenhang nicht mehr. Ein klassisches PAT gilt außerdem für
*alle* privaten Repos des Kontos, nicht nur für dieses — ein Fine-grained Token mit
Repository-Zugriff nur auf `m8rzel/telnyx-mcp` und `Contents: Read` ist die engere Wahl.
Und `git config --global` wirkt auf jedes Repo auf dem Rechner.

**So sieht es aus, wenn die Credentials fehlen:** `npx` bricht mit **Exit-Code 128** ab
(der Fehlercode von `git clone`) und schreibt keine erklärende Meldung in die Ausgabe —
nachgeprüft in einer Umgebung ohne jeden GitHub-Zugang, für `git+ssh` wie für
`git+https`. Startet der Server im Client also ohne verständlichen Grund nicht, ist das
der erste Verdacht. Den Aufruf einmal von Hand im Terminal starten, dann steht die
eigentliche Ursache da (`Permission denied (publickey)` bzw.
`could not read Username`).

Die radikale Alternative: Repo öffentlich machen und unter `@m8rzel/telnyx-mcp` auf npm
veröffentlichen — dann wäre der Eintrag schlicht `npx -y @m8rzel/telnyx-mcp`, ohne jede
Authentifizierung. Das ist eine Entscheidung über Sichtbarkeit, keine technische.

### Version festnageln

Ohne Angabe nimmt `npx` den aktuellen Stand des Standardbranches. Das heißt: Jeder Push
auf `main` ändert beim nächsten Start ungefragt die laufende Installation. Ein Commit-ish
hinter der URL verhindert das:

```text
git+ssh://git@github.com/m8rzel/telnyx-mcp.git#v1.0.0   ← Tag, empfohlen
git+ssh://git@github.com/m8rzel/telnyx-mcp.git#main      ← Branch, gleicht dem Standard
git+ssh://git@github.com/m8rzel/telnyx-mcp.git#a92a2f0   ← Commit, maximal eindeutig
```

Für den produktiven Eintrag gehört ein **Tag** in die Config. Aktualisieren ist dann ein
bewusster Schritt: Tag in der Config hochziehen, Client neu starten.

### Startzeit

Gemessen vom `npx`-Aufruf bis zur `initialize`-Antwort auf stdout, Node 22, Git-Remote
lokal (die Netzlatenz zu GitHub kommt obendrauf):

| Lauf | Zeit | Was passiert |
| --- | --- | --- |
| erster Start, leerer npm-Cache | **12–30 s** (4 Messungen: 11,6 / 27,5 / 27,9 / 29,9 s) | Lädt den MCP-SDK-Baum herunter: 92 Pakete, rein netzabhängig |
| jeder weitere Start | **0,7–1,5 s** | `git ls-remote` plus Start aus dem Cache |

Kompiliert wird **nie** — deshalb ist `dist/` eingecheckt (siehe unten).

Praktisch heißt das: **einmal im Terminal starten, bevor du den Eintrag in den Client
schreibst.** Danach ist der Cache warm und der Client startet in rund einer Sekunde. Ein
kalter Erststart von bis zu einer halben Minute kann sonst in den Start-Timeout eines
MCP-Clients laufen (bei Claude Code per `MCP_TIMEOUT` in Millisekunden anpassbar) — der
Server wäre dann nicht kaputt, nur zu langsam, und beim nächsten Versuch sofort da.

Zwei Feinheiten: Ein geänderter Commit-ish (Tag statt Branch) ist ein eigener
Cache-Eintrag, kostet also einmal wieder einen kalten Start. Und ohne Pin ist jeder neue
Commit auf `main` ebenfalls ein kalter Start.

### Warum `dist/` im Repository liegt

`npx <git-spec>` klont, installiert und packt das Paket. Gibt es ein `prepare`-Script,
installiert npm dafür zusätzlich **alle** Dev-Abhängigkeiten und kompiliert — bei jedem
kalten Start, auf dem Rechner des Nutzers. Das kostet Zeit und schafft eine Fehlerquelle,
die man aus dem MCP-Client kaum sieht: Schlägt der Build fehl, startet der Server nicht,
und die Meldung dazu versteckt sich in der npx-Ausgabe.

Deshalb liegt das Build-Ergebnis im Repository, `package.json` hat kein `prepare` und
`files` beschränkt das Paket auf `dist`. Der Preis: `npm run build` muss **vor** jedem
Commit laufen, sonst weichen Quelle und Build voneinander ab. Siehe
[CONTRIBUTING.md](CONTRIBUTING.md); `npm run verify:dist` prüft es.

## Why this exists

The official Telnyx connector ships 43 tools covering numbers, messaging, calls and the
voice AI stack — but **none of them generate speech from text**. The REST endpoint
`POST /v2/text-to-speech/speech` is fully capable (4,900+ voices across 13 providers,
`binary_output` returns `audio/mpeg` directly), it just is not exposed. This server wraps
exactly that endpoint, plus the pieces you actually need around it: pause handling,
segment joining, duration measurement and cost estimation.

## Tools

| Tool | Does | Parameters |
| --- | --- | --- |
| `list_voices` | Lists voices from `GET /v2/text-to-speech/voices`, filtered and paged. Returns `returned of matched of total` plus a per-provider count, never the full catalogue. | `language` (`"de"` matches de-DE/de-AT/de-CH, `"de-DE"` matches only that), `provider`, `search`, `limit` (default 50, max 200), `offset` |
| `speak` | Synthesises one text and writes an MP3. Returns the absolute path, bytes, measured duration, character count and estimated cost, plus the MP3 as an audio block (up to 8 MB; off with `TELNYX_TTS_EMBED_AUDIO=false`). | `text` (required), `voice` (required), `language`, `rate`, `text_type` (`text`\|`ssml`), `voice_settings`, `file_name` |
| `render_script` | Renders a markdown script with `[PAUSE n]` markers into one continuous MP3: text is split at sentence boundaries, synthesised segment by segment, and joined with real silence. Returns total duration plus per-segment durations, and the MP3 as an audio block up to 8 MB. | `script` (required), `voice` (required), `language`, `rate`, `voice_settings`, `max_chars` (default 1800), `lead_in_seconds`, `lead_out_seconds`, `file_name` |
| `estimate_cost` | Prices a character count, a text or a full script **without calling the API**. For a script it also returns segment/pause statistics. | one of `characters` / `text` / `script`, plus `voice` (required), `max_chars` |

### Script format

```markdown
# Heading — not spoken

Take a slow breath in.

[PAUSE 5]

And let it go.

[PAUSE 12]
```

- A line that consists of **only** `[PAUSE n]` becomes exactly n seconds of silence.
  `n` may be decimal, with a dot or a comma (`[PAUSE 2,5]`).
- Consecutive markers are added together.
- Headings, horizontal rules and lines that *mention* a marker without being one (the
  usual "Note: `[PAUSE 2]` = 2 seconds" legend) are dropped — never spoken, never timed.
- Text is packed into segments of at most `max_chars`, split only at sentence
  boundaries. A single sentence longer than the limit is kept whole rather than cut.

## Install

Zum Benutzen: nichts installieren, siehe [Einrichten](#einrichten--ein-eintrag-kein-clone).
Zum Entwickeln:

```bash
git clone git@github.com:m8rzel/telnyx-mcp.git
cd telnyx-mcp
npm install
npm run build
```

Requires Node 20 or newer. Runtime dependencies: `@modelcontextprotocol/sdk` and `zod` —
nothing else, in particular **no ffmpeg**.

## Configure

The API key is read from the environment only. It is never stored in this repository and
never appears in a log line or an error message. Without it the server exits immediately
with exit code 78.

| Variable | Required | Default | Meaning |
| --- | --- | --- | --- |
| `TELNYX_API_KEY` | yes | — | Telnyx API key (Portal → Auth → API Keys) |
| `TELNYX_TTS_OUTPUT_DIR` | no | `<os-temp>/telnyx-mcp` | Where MP3 files are written |
| `TELNYX_TTS_TIMEOUT_MS` | no | `120000` | HTTP timeout per attempt |
| `TELNYX_TTS_MAX_RETRIES` | no | `3` | Attempts per request (429/5xx/network, with backoff) |
| `TELNYX_TTS_EMBED_AUDIO` | no | `true` | `speak` and `render_script` also return the MP3 as an MCP audio block (up to 8 MB), so clients without access to the server's disk can attach it; `false` (also `0`/`no`/`off`) returns the JSON only |

### Wiring a local clone into an MCP client

Der Standardweg ist `npx` ([oben](#einrichten--ein-eintrag-kein-clone)). Wenn du am Code
arbeitest und den Clone statt GitHub einbinden willst:

```json
{
  "mcpServers": {
    "telnyx": {
      "command": "node",
      "args": ["/absolute/path/to/telnyx-mcp/dist/index.js"],
      "env": {
        "TELNYX_API_KEY": "your-telnyx-api-key",
        "TELNYX_TTS_OUTPUT_DIR": "/absolute/path/to/audio-output"
      }
    }
  }
}
```

Use absolute paths — the server is started as a child process and inherits no shell.
Transport is stdio; stdout is the protocol channel, so all diagnostics go to stderr.

## Fallback: mit Docker betreiben

Brauchst du nur, wenn der `npx`-Weg ausfällt — etwa weil auf dem Rechner kein `git` mit
GitHub-Zugang eingerichtet ist, der Server strikt isoliert laufen soll oder du eine
feste, lokal gebaute Fassung einfrieren willst. Der Nachteil liegt auf der Hand: ein
Clone, ein Image-Build und ein laufender Docker-Daemon statt einer Zeile in der Config.

Das Image ist ein zweistufiger Build auf `node:20-alpine`: Die erste Stufe installiert
alles und kompiliert TypeScript, die zweite übernimmt nur `node_modules` (ohne
Dev-Abhängigkeiten), `dist/` und `package.json`. Kein ffmpeg, kein Port, kein
`HEALTHCHECK` — ein stdio-Server hat nichts, womit eine Health-Probe reden könnte.

### Ein Befehl

```bash
git clone https://github.com/m8rzel/telnyx-mcp.git ~/mcp/telnyx-mcp
cd ~/mcp/telnyx-mcp && bash install.sh
```

Das ist alles. Kein Dateien-Verschieben, kein JSON-Editieren, kein manuelles Bauen.
Ab dem zweiten Mal genügt `./install.sh` — den ersten Lauf startest du über `bash`,
weil das Ausführungsbit einen `git clone` nicht zwingend übersteht; das Skript setzt
es dann selbst.

Was dabei passiert:

| Schritt | |
| --- | --- |
| 1 | Prüft, ob Docker installiert ist **und** der Daemon antwortet. Sonst Abbruch mit Hinweis auf Docker Desktop. |
| 2 | Baut das Image `telnyx-mcp` aus dem Repo-Verzeichnis — egal, aus welchem Ordner du das Skript aufrufst. |
| 3 | Legt den Audio-Ordner an: `$HOME/mcp/telnyx-audio`, oder was in `TELNYX_TTS_OUTPUT_DIR` steht. |
| 4 | Holt den API-Schlüssel aus `$TELNYX_API_KEY`, sonst aus einer vorhandenen `.env`, sonst fragt es dich (ohne die Eingabe anzuzeigen). Sichert ihn in `.env` mit `chmod 600`. |
| 5 | Registriert den Server in **Claude Code** (falls die CLI `claude` da ist) und in **Claude Desktop** (falls dessen Konfiguration existiert). Findet es keines von beiden, gibt es die fertige JSON-Konfiguration zum Kopieren aus. |
| 6 | Rauchtest: startet den Container mit genau der registrierten Befehlszeile und lässt ihn per JSON-RPC die vier Werkzeuge melden. |
| 7 | Sagt dir, wo die MP3s landen und dass Claude einmal neu starten muss. |

Das Skript ist **idempotent**: Nach einem `git pull` lässt du es einfach erneut laufen.
Einen bestehenden `telnyx`-Eintrag ersetzt es, andere MCP-Server lässt es unberührt —
und von der Claude-Desktop-Konfiguration legt es vor jeder Änderung eine Sicherungskopie
`claude_desktop_config.json.bak-<Zeitstempel>` an.

Optionen:

```bash
bash install.sh --non-interactive   # keine Rückfragen (Schlüssel muss vorliegen)
bash install.sh --no-register       # nur bauen und testen, nichts registrieren
bash install.sh --help
```

### Von Hand, falls du die Schritte einzeln willst

```bash
docker build -t telnyx-mcp .
mkdir -p ~/mcp/telnyx-audio

docker run --rm -i \
  -e TELNYX_API_KEY="$TELNYX_API_KEY" \
  -e TELNYX_TTS_OUTPUT_DIR="$HOME/mcp/telnyx-audio" \
  -v "$HOME/mcp/telnyx-audio:$HOME/mcp/telnyx-audio" \
  telnyx-mcp
```

Er wartet dann still auf JSON-RPC über stdin; `telnyx-mcp ready. Output directory: …` auf
stderr heißt, er läuft. Mit Strg-C wieder raus.

Und so sieht der Eintrag aus, den der Installer schreibt (`~/Library/Application
Support/Claude/claude_desktop_config.json` bzw. `claude mcp add`):

```json
{
  "mcpServers": {
    "telnyx": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TELNYX_API_KEY",
        "-e", "TELNYX_TTS_OUTPUT_DIR",
        "-v", "/Users/marcel/mcp/telnyx-audio:/Users/marcel/mcp/telnyx-audio",
        "telnyx-mcp"
      ],
      "env": {
        "TELNYX_API_KEY": "dein-telnyx-api-key",
        "TELNYX_TTS_OUTPUT_DIR": "/Users/marcel/mcp/telnyx-audio"
      }
    }
  }
}
```

`-e TELNYX_API_KEY` ohne Wert reicht die Variable aus dem `env`-Block durch, damit der
Schlüssel nicht in der Argumentliste eines `docker`-Prozesses auftaucht.

### Drei Stolpersteine

| Regel | Warum |
| --- | --- |
| `-i`, niemals `-t` | Ein TTY macht aus stdio ein Terminal: Zeileneditor, Echo und Steuersequenzen landen im Strom und zerlegen die JSON-RPC-Frames. `docker run -it` ist für eine Shell richtig und für einen MCP-Server falsch. |
| Der Audio-Ordner braucht **innen und außen denselben absoluten Pfad** | `speak` und `render_script` liefern den *Pfad* der MP3 zurück; die Audiodaten selbst nur als Audio-Block bis 8 MB (längere Dateien nur über den Pfad). Mountest du `~/mcp/telnyx-audio` nach `/data`, bekommt der Client `/data/foo.mp3` — einen Pfad, den es auf deinem Rechner nicht gibt. Das Verzeichnis auf sich selbst zu mounten und `TELNYX_TTS_OUTPUT_DIR` darauf zu setzen, hält beide Seiten deckungsgleich. |
| `--rm` | Der MCP-Client startet pro Sitzung einen Container und beendet ihn beim Schließen. Ohne `--rm` bleibt bei jedem Neustart ein gestoppter Container liegen. |

### Dateirechte

Der Container läuft als unprivilegierter `node`-User, der im Image mitkommt (uid 1000).
Unter Docker Desktop für macOS gehört der Bind-Mount ohnehin dem aufrufenden Benutzer,
dort ist nichts zu tun. Unter Linux schon: Ist die eigene uid nicht 1000, kann der Server
nicht in das gemountete Verzeichnis schreiben und `speak` scheitert mit `EACCES`. Der
Installer erkennt das und ergänzt dort automatisch `--user $(id -u):$(id -g)`. Von Hand:

```bash
docker run --rm -i --user "$(id -u):$(id -g)" \
  -e TELNYX_API_KEY="$TELNYX_API_KEY" \
  -e TELNYX_TTS_OUTPUT_DIR="$HOME/mcp/telnyx-audio" \
  -v "$HOME/mcp/telnyx-audio:$HOME/mcp/telnyx-audio" \
  telnyx-mcp
```

In einer MCP-Client-Konfiguration gehören dieselben Flags in das `args`-Array —
`"--user", "501:20"` mit den Zahlen aus `id -u` und `id -g`, weil `$(…)` dort nicht
ausgewertet wird.

### Optional: Image aus der GHCR statt lokal bauen

**Dieser Weg ist noch nicht aktiv.** Der Workflow dafür liegt als
`.github/docker.yml` im Repo — also *nicht* in `.github/workflows/`, wo GitHub ihn
ausführen würde. Grund: Dem schreibenden GitHub-Zugang fehlt der `workflow`-Scope,
ein Push nach `.github/workflows/` wird mit `403 insufficient scopes` abgelehnt.
Solange die Datei dort liegt, läuft nichts und es existiert kein Image in der GHCR.

Der Standardweg ist deshalb der lokale Build, den `install.sh` erledigt. Wer den
GHCR-Weg aktivieren will, verschiebt die Datei einmal von Hand und löscht den
erklärenden Kommentarblock an ihrem Anfang:

```bash
git mv .github/docker.yml .github/workflows/docker.yml
```

Danach veröffentlicht jeder Push auf `main` `ghcr.io/m8rzel/telnyx-mcp:latest` für
`linux/amd64` und `linux/arm64`; ein `v*`-Tag veröffentlicht zusätzlich `:1.2.3` und
`:1.2`. Weil dieses Repository privat ist, ist das Package ebenfalls privat — vor dem
Pull einmal anmelden, mit einem Personal Access Token (classic) mit dem Scope
`read:packages`:

```bash
docker login ghcr.io -u m8rzel        # Passwort = das Token, nicht das GitHub-Passwort
docker pull ghcr.io/m8rzel/telnyx-mcp:latest
```

## Speaking rate

Telnyx has **no single rate field**. The `rate` parameter here is a multiplier
(`1` = normal) that is translated per provider:

| Voice | How `rate` is sent | Range |
| --- | --- | --- |
| `Telnyx.Ultra.*`, `Telnyx.Grok.*` | `voice_settings.voice_speed` | 0.5–2.0 |
| `Minimax.*` | `voice_settings.speed` | 0.5–2.0 |
| `Soniox.*` | `voice_settings.speed` | 0.7–1.3 |
| `aws.Polly.*`, `azure.*` | text is wrapped in `<speak><prosody rate="85%">…</prosody></speak>` and `text_type` is set to `ssml` | 0.2–2.0 |
| everything else (Kokoro, Qwen3, Bayan, Sukhan, ElevenLabs, Resemble, Inworld, Fish, xAI) | **rejected with an explanation** | — |

Only AWS Polly and Azure accept SSML at all. A rate for a voice that cannot do it is an
error before any request is sent, rather than a silently ignored parameter — you would
otherwise pay for audio at the wrong tempo. Note that the SSML wrapper adds characters,
and Telnyx bills per character, so the reported cost includes it.

## How the audio is assembled

`render_script` makes one API call per speech segment and then joins everything on **MP3
frame level** — no decoding, no re-encoding, no quality loss, no ffmpeg:

- Silence is generated as real MPEG Layer III frames that match the format Telnyx
  returned (version, sample rate, channel mode, bitrate). The payload after each 4-byte
  header is all zeroes, which with the protection bit set to "no CRC" means
  `part2_3_length = 0` for every granule: the decoder reads no main data and outputs one
  frame of silence.
- Pause lengths are quantised to whole frames (24 ms at 24 kHz, 26 ms at 44.1 kHz). The
  result reports the **actual** duration, and `requested_seconds` whenever it differs.
- Duration is computed exactly from the frame headers (`samples / sample rate`), not
  estimated from the bitrate.
- Parts with different sample rates or channel counts are refused instead of being glued
  into a file that plays at the wrong speed.

That costs ~200 lines of header arithmetic and keeps the dependency list at two packages;
requiring ffmpeg for the same job would be a ~70 MB external binary.

`scripts/verify-audio.mjs` checks this against an independent implementation: ffmpeg
encodes a tone, this code builds the silence and joins the parts, and ffmpeg then decodes
and measures the result. It needs ffmpeg on `PATH` (or `FFMPEG_PATH`) and is therefore not
part of `npm test`:

```bash
npm run build && node scripts/verify-audio.mjs
```

## Cost

Telnyx bills per synthesised character. List prices used by `estimate_cost`
(source: <https://telnyx.com/pricing/text-to-speech>):

| Tier | USD per character | 14,000-character script |
| --- | --- | --- |
| Telnyx TTS (Kokoro) | $0.000003 | ~$0.04 |
| Telnyx Ultra, Qwen3 | $0.000032 | ~$0.45 |
| Telnyx HD Voices | $0.000048 | ~$0.67 |
| Amazon Polly standard | $0.000009 | ~$0.13 |
| Amazon Polly neural | $0.000024 | ~$0.34 |
| MiniMax | $0.000034 | ~$0.48 |
| Resemble, Murf | $0.000008 | ~$0.11 |
| Inworld Mini / Max | $0.0000055 / $0.00001 | ~$0.08 / ~$0.14 |

**ElevenLabs and Azure are bring-your-own-key.** Using `elevenlabs.*` or `azure.*` voices
through Telnyx requires your own provider key stored in your Telnyx account; those
requests are billed by ElevenLabs/Azure, not per Telnyx character. `estimate_cost`
returns `null` for them instead of inventing a number.

## Limits

- **Character limit per request is undocumented.** The default `max_chars` of 1800 is a
  conservative choice, not a Telnyx specification. Raise it if long segments work for you.
- **Rate limits for this endpoint are undocumented.** Segments are synthesised
  sequentially, never in parallel; 429 responses are retried with backoff and honour
  `Retry-After`.
- **MP3 only.** `render_script` needs MPEG Layer III to join frames. Voices that return
  PCM or another format fail with a clear message rather than a corrupt file.
- Sentence splitting is a regular expression on `. ! ? …` followed by whitespace, so an
  abbreviation like "z. B." can be treated as a sentence end. That only affects where a
  segment boundary falls, never the spoken text.

## Development

```bash
npm run lint         # eslint, type-aware
npm run build        # tsc -> dist/
npm test             # vitest, 90 tests, no network
npm run check        # all three
npm run verify:dist  # baut neu und bricht ab, wenn dist/ vom Commit abweicht
```

`dist/` ist eingecheckt (Begründung [oben](#warum-dist-im-repository-liegt)) — jeder
Commit, der `src/` berührt, muss das neu gebaute `dist/` mitbringen. Details in
[CONTRIBUTING.md](CONTRIBUTING.md).

Dependency versions are pinned exactly, so `npm install` reproduces the tested tree even
though no lockfile is committed. The Docker build follows the same rule: it runs
`npm install`, and automatically switches to `npm ci` as soon as a `package-lock.json`
is committed.

Tests mock the HTTP layer and run against real LAME-encoded MP3 fixtures (base64-embedded
in `tests/fixtures/index.ts`, so the repository holds no binary blobs), which means the
suite runs offline and without an API key. Regenerate the fixtures with
`node scripts/make-fixtures.mjs` (needs ffmpeg).

## Security

- The key lives in `TELNYX_API_KEY` only. There is no key in the code, the tests, the
  examples or the git history — `.env` is git-ignored and `.env.example` holds variable
  names only.
- Every error message passes through a redaction filter that strips the key and anything
  shaped like a bearer token before it is returned or logged.
- `file_name` is reduced to a safe base name; the resolved path is verified to stay
  inside the configured output directory, so no input can write outside it.
- Audio is written to disk and referenced by path. Files up to 8 MB are additionally
  returned base64-encoded as an MCP audio block, so clients without access to this disk
  (containers, remote agents) get the audio too; larger files — a 30-minute hypnosis
  script is around 14 MB — are referenced by path only. `TELNYX_TTS_EMBED_AUDIO=false`
  turns the audio block off.

## License

MIT — see [LICENSE](LICENSE).

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation4/5

Each tool maps to a distinct step in the TTS workflow: discovering voices, synthesising single text, rendering multi-segment scripts, and estimating cost without an API call. The only mild overlap is between speak and render_script, both producing MP3s, but the descriptions make the plain-text vs markdown-script-with-pauses boundary clear.

Naming Consistency4/5

All names use snake_case and are mostly verb_noun (list_voices, render_script, estimate_cost). The bare verb speak is a minor deviation but still readable and unambiguous in this context.

Tool Count4/5

Four tools is compact and each earns its place in the voice-synthesis flow. Slightly thin — a voice-detail or provider-listing tool could round it out — but nothing feels redundant.

Completeness4/5

The surface covers the core lifecycle: discover voices, preview cost, synthesise text, and render full scripts with silence insertion. Minor gaps exist (no voice metadata lookup, no output format/quality options beyond MP3, no batch/list of generated files), but agents can work around them.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues