Skip to main content
Glama

Bakbak MCP server

The official Model Context Protocol server for Bakbak, 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 and list_voices. Full documentation: https://docs.litwizlabs.com/documentation/tts-mcp.

Contents: Get an API key · Set up your client · Tools · Example prompts · Configuration · Errors · Retries and timeouts · Latency tips · Privacy · Self-hosting · Development

Get an API key

Create a key in the Bakbak dashboard. Synthesis uses your Bakbak credits for every character; listing voices is free.

Related MCP server: Edge TTS MCP

Set up your client

Local mode needs Node.js 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 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:

{
  "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):

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

Hosted, with your key as a header:

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 · Add Bakbak (hosted) to Cursor

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:

{
  "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:

{
  "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):

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

Windsurf

Add to ~/.codeium/windsurf/mcp_config.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:

{
  "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, 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/ directory has a Dockerfile-based compose file, a Caddy example and the operational notes (reverse proxies, Cloudflare, scaling, secret rotation).

Development

See CONTRIBUTING.md. Security issues: SECURITY.md.

License

Apache-2.0. Copyright 2026 Raya Voice AI.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers