Repository avatar
Other Tools
v1.0.0-rc.2
active

bakbak-mcp

io.github.raya-voice-ai/bakbak-mcp

Text to speech in Hindi, other Indian languages and English, with the Bakbak API.

Documentation

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 · Languages and models · 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.

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.

ParameterTypeDefaultDescription
textstringrequiredThe text, up to 50,000 characters. Hindi must be in Devanagari script.
languagestringrequiredhi, 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_idstringfirst voice for the languageA voice id from list_voices.
modelstringthe voice's modelstandard or m1. Must be the voice's own model.
speednumber1.0Speaking rate, 0.5 to 1.5. Standard voices only: m1 voices accept it and speak at their own pace.
output_formatobject{"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_pathstringa new fileLocal 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.
overwritebooleanfalseLocal mode only. Replace output_path if it exists; otherwise an existing file is never touched.
include_audiobooleanfalseAlso 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):

FieldDescription
file_pathLocal: absolute path of the new file.
audio_url, expires_atHosted: private download link and when it stops working (one hour).
formatcontainer, encoding, sample_rate and mime_type of the audio.
duration_secondsLength of the audio, measured from the bytes.
charactersCharacters synthesized (Unicode code points).
voice_id, model, languageWhat was used.
request_idsBakbak 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.

ParameterTypeDefaultDescription
languagestringallOnly voices for this language, e.g. hi.
modelstringallOnly voices of this model: standard or m1.
querystringnoneOnly voices whose name contains this text (case-insensitive).
limitinteger50Most voices to return (1–500).

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

Languages and models

ModelLanguages
m1Hindi hi, English en, Kannada kn
standardHindi hi, Indian English en-in, US English en-us, Assamese as, Bengali bn, Gujarati gu, Kannada kn, Malayalam ml, Marathi mr, Nepali ne, Tamil ta, Telugu te

That is the voice catalog of 22 November 2026; list_voices is the source of truth. Punjabi (pa) is accepted by the API but has no voice yet. speed changes standard voices only.

Example prompts

  • "List the Hindi voices."
  • "Say 'आपका ऑर्डर कल तक पहुँच जाएगा।' in Hindi with an m1 voice."
  • "Turn this blog post into a narration with a standard voice, a little slower than normal." (long text is fine; speed changes standard voices only)
  • "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

VariableDefaultMeaning
BAKBAK_API_KEYnoneYour API key. Without it the server still starts and lists its tools; every call explains how to set the key.
BAKBAK_BASE_URLhttps://hub.getraya.appAPI 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_LEVELinfodebug, info, warn or error. Logs are JSON lines on stderr; stdout carries only the protocol.

Hosted mode (bakbak-mcp --http)

VariableDefaultMeaning
MCP_PUBLIC_URLrequiredPublic origin, e.g. https://mcp.bakbak.si. Every advertised URL is built from it, never from the Host header.
MCP_TOKEN_SECRETrequiredSecret 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_URLhttps://hub.getraya.appAPI base URL.
AUDIO_DIR<tmp>/bakbak-mcp-audioWhere audio is kept until it expires.
AUDIO_TTL1hHow long audio links work: seconds, or 90s, 30m, 1h.
AUDIO_MAX_BYTES2GCap on stored audio; the oldest files go first. Bytes, or 512M, 2G.
AUDIO_MAX_BYTES_PER_KEYa quarter of AUDIO_MAX_BYTESStored audio per API key; a key's own oldest files go first, so one key cannot push out everyone else's links.
MAX_OUTPUT_BYTES512MMost audio one text_to_speech call may produce, estimated from the text before any credits are spent.
TTS_CONCURRENCY_PER_KEY2Most text_to_speech calls running at once per API key.
INFLIGHT_AUDIO_BYTES1GMost estimated audio being produced at once across all calls; at least MAX_OUTPUT_BYTES.
PORT8080Listening port.
HOST0.0.0.0Listening address.
TRUSTED_PROXIESloopback and private rangesCIDRs of reverse proxies whose CF-Connecting-IP / X-Forwarded-For are believed (for per-address rate limits). Empty trusts none.
LOG_LEVELinfoAs 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.

NPM
bakbak-mcp
Install Command
npm install bakbak-mcp

Remote