
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
- Open Settings → Connectors and choose Add custom connector. (On Team and Enterprise plans an owner adds it for the organization.)
- Name it
Bakbakand enter the URLhttps://mcp.bakbak.si/mcp. - 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-mcpover stdio withBAKBAK_API_KEYin its environment. - Hosted: connect to
https://mcp.bakbak.si/mcp(streamable HTTP, protocol revisions 2026-07-28 and 2025-era) withAuthorization: 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 behttps,httpon a loopback address, or a native app's own scheme such ascursor://(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. Standard voices only: m1 voices accept it and speak at their own pace. |
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.
Languages and models
| Model | Languages |
|---|---|
m1 | Hindi hi, English en, Kannada kn |
standard | Hindi 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;
speedchanges standard voices only) - "Make an 8 kHz μ-law version of this IVR greeting in Tamil for our phone system:
output_formatraw,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_idandmodeltogether to skip the voice lookup entirely. - Shorter text answers sooner: the server makes one request per 5,000 characters.
- Lower sample rates and
mp3make smaller files, which matters forinclude_audioand 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.
bakbak-mcpnpm install bakbak-mcp