Skip to main content
Glama
README.md
# Bakbak MCP server

The official [Model Context Protocol](https://modelcontextprotocol.io) server for
[Bakbak](https://bakbak.getraya.app), the text-to-speech API by Raya. It lets Claude, Cursor,
VS Code, Windsurf and any other MCP client speak text in Hindi, other Indian languages and
English:

> "Read this paragraph aloud in Hindi with a calm female voice and save it as an MP3."

It runs two ways:

- **Local** (`npx bakbak-mcp`, stdio): audio is saved as files on your computer.
- **Hosted** (`https://mcp.bakbak.si/mcp`, streamable HTTP): nothing to install; audio comes
  back as a private download link. Sign in with OAuth (claude.ai connectors) or send your API
  key as a header.

Both offer the same two tools: [`text_to_speech`](#text_to_speech) and
[`list_voices`](#list_voices). Full documentation:
<https://docs.litwizlabs.com/documentation/tts-mcp>.

**Contents:** [Get an API key](#get-an-api-key) · [Set up your client](#set-up-your-client) ·
[Tools](#tools) · [Example prompts](#example-prompts) · [Configuration](#configuration) ·
[Errors](#errors) · [Retries and timeouts](#retries-and-timeouts) ·
[Latency tips](#latency-tips) · [Privacy](#privacy) · [Self-hosting](#self-hosting) ·
[Development](#development)

## Get an API key

Create a key in the [Bakbak dashboard](https://bakbak.getraya.app). Synthesis uses your Bakbak
credits for every character; listing voices is free.

## Set up your client

Local mode needs [Node.js](https://nodejs.org) 22 or newer. The Claude Desktop bundle runs on
the Node.js built into Claude Desktop, so it needs nothing installed. Replace
`YOUR_BAKBAK_API_KEY` with your key.

### Claude Desktop

**One click:** download `bakbak-mcp-<version>.mcpb` from the
[latest release](https://github.com/raya-voice-ai/bakbak-mcp/releases/latest) and open it.
Claude Desktop asks for your API key and where to save audio (default `Documents/Bakbak`).

**Or by hand:** Settings → Developer → Edit Config, then add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "bakbak": {
      "command": "npx",
      "args": ["-y", "bakbak-mcp"],
      "env": { "BAKBAK_API_KEY": "YOUR_BAKBAK_API_KEY" }
    }
  }
}
```

### Claude Code

Local (audio files go to `~/Documents/Bakbak` unless you set `BAKBAK_MCP_OUTPUT_DIR`):

```sh
claude mcp add bakbak -e BAKBAK_API_KEY=YOUR_BAKBAK_API_KEY -- npx -y bakbak-mcp
```

Hosted, with your key as a header:

```sh
claude mcp add --transport http bakbak https://mcp.bakbak.si/mcp \
  --header "Authorization: Bearer YOUR_BAKBAK_API_KEY"
```

Or hosted without a header: run `claude mcp add --transport http bakbak
https://mcp.bakbak.si/mcp`, then `/mcp` in Claude Code to sign in with OAuth.

### claude.ai

1. Open **Settings → Connectors** and choose **Add custom connector**.
   (On Team and Enterprise plans an owner adds it for the organization.)
2. Name it `Bakbak` and enter the URL `https://mcp.bakbak.si/mcp`.
3. Click **Connect**. A Bakbak page opens: paste your API key and click **Connect**.

Audio comes back as a private link that works for one hour.

### Cursor

[Add Bakbak (local) to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=bakbak&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJha2Jhay1tY3AiXSwiZW52Ijp7IkJBS0JBS19BUElfS0VZIjoiWU9VUl9CQUtCQUtfQVBJX0tFWSJ9fQ==)
· [Add Bakbak (hosted) to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=bakbak&config=eyJ1cmwiOiJodHRwczovL21jcC5iYWtiYWsuc2kvbWNwIn0=)

For the local server, replace `YOUR_BAKBAK_API_KEY` in Cursor's MCP settings. The hosted server
needs no key in the config: Cursor opens the Bakbak sign-in page, where you paste your key once.
Or add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "bakbak": {
      "command": "npx",
      "args": ["-y", "bakbak-mcp"],
      "env": { "BAKBAK_API_KEY": "YOUR_BAKBAK_API_KEY" }
    }
  }
}
```

For the hosted server use `{ "url": "https://mcp.bakbak.si/mcp" }` as the server entry (sign in
with OAuth), or add `"headers": { "Authorization": "Bearer YOUR_BAKBAK_API_KEY" }` to skip the
sign-in.

### VS Code

Add `.vscode/mcp.json` to your workspace. VS Code prompts for the key once and stores it
securely:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "bakbak-api-key",
      "description": "Bakbak API key",
      "password": true
    }
  ],
  "servers": {
    "bakbak": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "bakbak-mcp"],
      "env": { "BAKBAK_API_KEY": "${input:bakbak-api-key}" }
    }
  }
}
```

For the hosted server, use this server entry instead (or omit `headers` to sign in with
OAuth):

```json
"bakbak": {
  "type": "http",
  "url": "https://mcp.bakbak.si/mcp",
  "headers": { "Authorization": "Bearer ${input:bakbak-api-key}" }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "bakbak": {
      "command": "npx",
      "args": ["-y", "bakbak-mcp"],
      "env": { "BAKBAK_API_KEY": "YOUR_BAKBAK_API_KEY" }
    }
  }
}
```

Hosted: `{ "serverUrl": "https://mcp.bakbak.si/mcp", "headers": { "Authorization": "Bearer
YOUR_BAKBAK_API_KEY" } }`.

### Any other client

- Local: run `npx -y bakbak-mcp` over stdio with `BAKBAK_API_KEY` in its environment.
- Hosted: connect to `https://mcp.bakbak.si/mcp` (streamable HTTP, protocol revisions
  2026-07-28 and 2025-era) with `Authorization: Bearer <key>`, `X-API-Key: <key>`, or OAuth 2.1
  (discovery via `/.well-known/oauth-protected-resource/mcp`, dynamic client registration or
  client ID metadata documents, PKCE S256). OAuth redirect URIs must be `https`, `http` on a
  loopback address, or a native app's own scheme such as `cursor://` (RFC 8252).

## Tools

Parameter names are the Bakbak API's own (`voice_id`, `output_format`, …), so prompts, code and
`curl` read the same. Unknown parameters are refused; there is never a parameter for an API key.

### `text_to_speech`

Converts text to speech and saves it (local) or returns a link (hosted). Uses credits.

| Parameter       | Type    | Default                                                          | Description                                                                                                                                                                                             |
| --------------- | ------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`          | string  | required                                                         | The text, up to 50,000 characters. Hindi must be in Devanagari script.                                                                                                                                  |
| `language`      | string  | required                                                         | `hi`, `mr`, `te`, `kn`, `bn`, `as`, `gu`, `ne`, `ml`, `ta`, `pa`, `en`, `en-in` or `en-us` (and any language the API adds). English m1 voices use `en`; standard English voices use `en-in` or `en-us`. |
| `voice_id`      | string  | first voice for the language                                     | A voice id from `list_voices`.                                                                                                                                                                          |
| `model`         | string  | the voice's model                                                | `standard` or `m1`. Must be the voice's own model.                                                                                                                                                      |
| `speed`         | number  | `1.0`                                                            | Speaking rate, 0.5 to 1.5.                                                                                                                                                                              |
| `output_format` | object  | `{"container":"wav","encoding":"pcm_s16le","sample_rate":24000}` | `container` `wav`, `mp3` or `raw`; `encoding` `pcm_s16le`, `pcm_f32le`, `pcm_mulaw` or `pcm_alaw` (required for wav and raw, omitted for mp3); `sample_rate` 8000, 16000, 22050 or 24000.               |
| `output_path`   | string  | a new file                                                       | Local mode only. An absolute path, or one relative to the output directory (and inside it). Its directory must exist and its extension must match the format.                                           |
| `overwrite`     | boolean | `false`                                                          | Local mode only. Replace `output_path` if it exists; otherwise an existing file is never touched.                                                                                                       |
| `include_audio` | boolean | `false`                                                          | Also return the audio inline as an MCP audio block, for audio up to 1 MB (about 20 s of the default WAV). Larger audio is still saved, and the call explains the limit.                                 |

It returns `structuredContent` (and the same JSON as text, after a one-line summary):

| Field                           | Description                                                          |
| ------------------------------- | -------------------------------------------------------------------- |
| `file_path`                     | Local: absolute path of the new file.                                |
| `audio_url`, `expires_at`       | Hosted: private download link and when it stops working (one hour).  |
| `format`                        | `container`, `encoding`, `sample_rate` and `mime_type` of the audio. |
| `duration_seconds`              | Length of the audio, measured from the bytes.                        |
| `characters`                    | Characters synthesized (Unicode code points).                        |
| `voice_id`, `model`, `language` | What was used.                                                       |
| `request_ids`                   | Bakbak request ids, for support.                                     |

Generated files are named `<language>_<voice>_<UTC time>_<random>.<ext>`, for example
`hi_Kavya_20261121T143205Z_k3x9q2.wav`, with the extension of the real format: `.wav`, `.mp3`,
or for raw audio `.pcm` (16-bit), `.f32`, `.ulaw` or `.alaw`.

**Long text.** One API request takes up to 5,000 characters. Longer text is split at sentence
boundaries with the Bakbak SDK's segmenter and the pieces become one file: WAV and raw audio
stream every piece over one WebSocket and join the samples under a single WAV header; MP3 makes
one request per piece and joins the frames. Clients that send a progress token get a progress
notification per piece.

### `list_voices`

Lists voices. Free. Read-only.

| Parameter  | Type    | Default | Description                                                   |
| ---------- | ------- | ------- | ------------------------------------------------------------- |
| `language` | string  | all     | Only voices for this language, e.g. `hi`.                     |
| `model`    | string  | all     | Only voices of this model: `standard` or `m1`.                |
| `query`    | string  | none    | Only voices whose name contains this text (case-insensitive). |
| `limit`    | integer | `50`    | Most voices to return (1–500).                                |

Returns `{ "voices": [{ "id", "name", "language", "model" }], "count", "total" }`, where
`total` counts every match before the limit.

## Example prompts

- "List the Hindi voices."
- "Say 'आपका ऑर्डर कल तक पहुँच जाएगा।' in Hindi with an m1 voice."
- "Turn this blog post into an MP3 narration, a little slower than normal." (long text is fine)
- "Make an 8 kHz μ-law version of this IVR greeting in Tamil for our phone system:
  `output_format` raw, `pcm_mulaw`, 8000."
- "Welcome राहुल शर्मा to the meetup in English and save it to `~/Desktop/welcome.wav`."

The server tells the model to pick a voice with `list_voices`, to pass the voice's own model,
to write Hindi in Devanagari, and that synthesis costs credits.

## Configuration

Configuration is by environment variable only.

### Local mode

| Variable                | Default                                                         | Meaning                                                                                                       |
| ----------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `BAKBAK_API_KEY`        | none                                                            | Your API key. Without it the server still starts and lists its tools; every call explains how to set the key. |
| `BAKBAK_BASE_URL`       | `https://hub.getraya.app`                                       | API base URL, for example a staging deployment.                                                               |
| `BAKBAK_MCP_OUTPUT_DIR` | `~/Documents/Bakbak` (or `~/Bakbak` if there is no `Documents`) | Where new audio files go. Created when needed; `~` is expanded.                                               |
| `LOG_LEVEL`             | `info`                                                          | `debug`, `info`, `warn` or `error`. Logs are JSON lines on stderr; stdout carries only the protocol.          |

### Hosted mode (`bakbak-mcp --http`)

| Variable                  | Default                        | Meaning                                                                                                                                                              |
| ------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MCP_PUBLIC_URL`          | required                       | Public origin, e.g. `https://mcp.bakbak.si`. Every advertised URL is built from it, never from the `Host` header.                                                    |
| `MCP_TOKEN_SECRET`        | required                       | Secret for sealing OAuth tokens: at least 32 characters (`openssl rand -base64 48`). Rotate with `new_kid:new_secret,old_kid:old_secret`: the first seals, all open. |
| `BAKBAK_BASE_URL`         | `https://hub.getraya.app`      | API base URL.                                                                                                                                                        |
| `AUDIO_DIR`               | `<tmp>/bakbak-mcp-audio`       | Where audio is kept until it expires.                                                                                                                                |
| `AUDIO_TTL`               | `1h`                           | How long audio links work: seconds, or `90s`, `30m`, `1h`.                                                                                                           |
| `AUDIO_MAX_BYTES`         | `2G`                           | Cap on stored audio; the oldest files go first. Bytes, or `512M`, `2G`.                                                                                              |
| `AUDIO_MAX_BYTES_PER_KEY` | a quarter of `AUDIO_MAX_BYTES` | Stored audio per API key; a key's own oldest files go first, so one key cannot push out everyone else's links.                                                       |
| `MAX_OUTPUT_BYTES`        | `512M`                         | Most audio one `text_to_speech` call may produce, estimated from the text before any credits are spent.                                                              |
| `TTS_CONCURRENCY_PER_KEY` | `2`                            | Most `text_to_speech` calls running at once per API key.                                                                                                             |
| `INFLIGHT_AUDIO_BYTES`    | `1G`                           | Most estimated audio being produced at once across all calls; at least `MAX_OUTPUT_BYTES`.                                                                           |
| `PORT`                    | `8080`                         | Listening port.                                                                                                                                                      |
| `HOST`                    | `0.0.0.0`                      | Listening address.                                                                                                                                                   |
| `TRUSTED_PROXIES`         | loopback and private ranges    | CIDRs of reverse proxies whose `CF-Connecting-IP` / `X-Forwarded-For` are believed (for per-address rate limits). Empty trusts none.                                 |
| `LOG_LEVEL`               | `info`                         | As above.                                                                                                                                                            |

## Errors

Every failure is a tool result with `isError: true`, never a protocol error, so the model can
read it and act. The first text block is a sentence plus one next step; the second is JSON:

```json
{
  "error": {
    "message": "Your balance is too low for this request.",
    "next_step": "The account is out of credits. Add credits at https://bakbak.getraya.app, then try again.",
    "status": 402,
    "error_code": "insufficient_credits",
    "request_id": "req_…",
    "retryable": false
  }
}
```

`message`, `error_code` and `request_id` come from the API unchanged; every `error_code` is
described at <https://docs.litwizlabs.com/documentation/tts-errors>. Invalid arguments
(including an unknown parameter) are reported the same way. A missing key names
`BAKBAK_API_KEY` and the dashboard. In hosted mode, a request without valid credentials gets
HTTP 401 with `WWW-Authenticate: Bearer resource_metadata="…"`, which starts the client's
OAuth flow.

Hosted mode also refuses, as tool errors and before spending credits, a call whose audio would
exceed `MAX_OUTPUT_BYTES` (the message suggests `mp3`, `pcm_s16le`, a lower sample rate or
splitting the text) and a call beyond `TTS_CONCURRENCY_PER_KEY` running calls for the key.

## Retries and timeouts

The server uses the [Bakbak JS SDK](https://github.com/raya-voice-ai/bakbak-js), which retries
connection failures, timeouts and retryable statuses (429, 5xx) up to twice with backoff, and
honours `Retry-After`. It never retries once audio has started: that audio is billed, and a
retry would bill it again. The read timeout is 60 s between bytes. Errors say whether retrying
can help (`retryable`).

In hosted mode, responses are streamed with a keep-alive comment every 15 s, so proxies do not
cut long calls. Some clients stop waiting for a tool after a few minutes (claude.ai after about
four); for very long texts, use local mode or split the text across calls.

## Latency tips

- Local mode opens the API connection and caches the voice list at startup, so the first call
  pays no handshake.
- Pass `voice_id` and `model` together to skip the voice lookup entirely.
- Shorter text answers sooner: the server makes one request per 5,000 characters.
- Lower sample rates and `mp3` make smaller files, which matters for `include_audio` and
  downloads.

## Privacy

- **Local mode** sends text only to the Bakbak API you configured. Audio stays on your computer.
  Nothing else is contacted: no telemetry, no update checks.
- **Hosted mode** (`mcp.bakbak.si`) keeps no database:
  - Your API key is checked with Bakbak and then exists only inside encrypted tokens (AES-256-GCM)
    held by your MCP client. Access tokens last one hour, refresh tokens 30 days. Deleting the
    key in the dashboard ends every connection that uses it.
  - Generated audio is stored on the server's disk for one hour under an unguessable link, then
    deleted. Anyone with the link can download it until then.
  - Text is sent to the Bakbak API and is not stored or logged by this server. Logs record
    request ids, sizes, timings, the caller's IP address and a one-way fingerprint of the key.

Bakbak's privacy policy: <https://bakbak.si/privacy-policy>.

## Self-hosting

`bakbak-mcp --http` runs the hosted server. The [`deploy/`](deploy/README.md) directory has a
Dockerfile-based compose file, a Caddy example and the operational notes (reverse proxies,
Cloudflare, scaling, secret rotation).

## Development

See [CONTRIBUTING.md](CONTRIBUTING.md). Security issues: [SECURITY.md](SECURITY.md).

## License

[Apache-2.0](LICENSE). Copyright 2026 Raya Voice AI.