vbee-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
vbee-mcp
Unofficial MCP server for vbee.vn — Vietnamese Text-to-Speech (TTS) and Speech-to-Text (STT).
Not affiliated with vbee.vn. Use at your own risk; API behavior and quotas are controlled by vbee.
Install
Requires Python 3.10+.
pip install -e .
# or, with dev tooling (pytest, ruff):
pip install -e '.[dev]'This installs the vbee-mcp console script, which runs the MCP server over stdio.
Related MCP server: ElevenLabs MCP Server
Configuration
Environment variables:
Variable | Required | Default | Description |
| yes | — | App ID from https://studio.vbee.vn/apps |
| yes | — | API token (Bearer). Never commit it. |
| no |
| API base URL |
| no | — | Fallback webhook for batch (async) TTS/STT |
The server starts without credentials; they are only required when a tool is actually called. The server does not load .env files — environment variables must be exported in your shell or provided by your MCP client config (e.g. the env block below). .env.example is provided as a reference for the variable names only.
Example MCP client config (Claude Desktop / compatible):
{
"mcpServers": {
"vbee": {
"command": "vbee-mcp",
"env": {
"VBEE_APP_ID": "your-app-id",
"VBEE_TOKEN": "your-token"
}
}
}
}Tools
1. tts_synthesize — Realtime TTS (sync)
POST /v1/tts with mode=sync. Text ≤ 300 chars (required).
Params: text (req), voice_code (req), output_format (mp3|wav|pcm, default mp3), bitrate (8|16|32|64|128, default 128), speed (0.25–1.9, default 1.0), sample_rate (8000|16000|22050|24000|32000|44100|48000, optional), output_path (optional).
The response is raw audio. If output_path is given, the file is written and the tool returns {output_path, content_type, bytes, ...}; otherwise it returns {audio_base64, content_type, bytes, ...}.
{"text": "Xin chào", "voice_code": "hn_female_ngochuyen_full_48k-fhg", "output_path": "/tmp/out.mp3"}2. tts_synthesize_async — Batch TTS (async)
POST /v1/tts with mode=async. Text up to 100,000 chars.
Params: text (req), voice_code (req), output_format (mp3|wav, default mp3), bitrate, speed, sample_rate, emphasis_intensity (0–100, multiple of 10, optional), client_pause (object optional: major_break/medium_break/paragraph_break/sentence_break in seconds), webhook_url (optional but the API currently requires it — falls back to VBEE_WEBHOOK_URL).
Returns {requestId, status}.
{"text": "...", "voice_code": "hn_female_ngochuyen_full_48k-fhg", "webhook_url": "https://example.com/hook"}3. tts_get_request — Poll batch TTS
GET /v1/tts/requests/{requestId} → {requestId, status, audioLink?, error_code?, error_message?}.
Note: audioLink expires after 3 minutes; generated audio is stored for 3 days.
Example invocation:
{"request_id": "9f2c1a7e-1234-4abc-8def-000000000000"}Example response:
{"requestId": "9f2c1a7e-1234-4abc-8def-000000000000", "status": "COMPLETED", "audioLink": "https://..."}4. stt_transcribe — Realtime STT (sync)
POST /v1/stt, multipart/form-data, mode=sync. WAV only, file < 10s and < 10MB.
Params: exactly one of file_path or audio_url; optional webhook_url.
Returns {transcriptId, status, transcript, utterances[], audioDurationSeconds}. audioDurationSeconds is used for prepaid billing.
Example invocation:
{"file_path": "/path/to/audio.wav"}or with a remote URL:
{"audio_url": "https://example.com/audio.wav", "webhook_url": "https://example.com/hook"}5. stt_transcribe_async — Batch STT (async)
Same endpoint, mode=async. File < 100MB. webhook_url optional (recommended; falls back to VBEE_WEBHOOK_URL).
Returns {transcriptId, status}.
Example invocation:
{"file_path": "/path/to/long-audio.wav", "webhook_url": "https://example.com/hook"}or with a remote URL (falls back to VBEE_WEBHOOK_URL when webhook_url is omitted):
{"audio_url": "https://example.com/long-audio.wav"}6. stt_get_transcript — Poll STT
GET /v1/stt/transcripts/{transcriptId} → transcript object. Poll every 2–5 seconds.
Example invocation:
{"transcript_id": "c3d4e5f6-1234-4abc-8def-000000000000"}Example response:
{"transcriptId": "c3d4e5f6-1234-4abc-8def-000000000000", "status": "COMPLETED", "transcript": "Xin chào...", "utterances": [], "audioDurationSeconds": 12.4}7. list_voices — List voices
GET https://vbee.vn/api/public/v1/voices with App-Id + Bearer headers.
Params: voice_ownership (VBEE|COMMUNITY|PERSONAL, required by the API — the tool always sends it and defaults to VBEE), code, language_code (e.g. vi-VN), gender (male|female), limit (1–100, default 20), cursor.
Returns {result: {pagination, voices[]}, status}.
Example invocation (list the first 5 Vietnamese female VBEE voices):
{"voice_ownership": "VBEE", "language_code": "vi-VN", "gender": "female", "limit": 5}Example invocation (paginate):
{"limit": 20, "cursor": "next-cursor-from-previous-response"}API limits & gotchas
Realtime TTS supports only 5 voices today: HN - Ngọc Huyền, SG - Tường Vy, HN - Mai Phương, SG - Lan Trinh, SG - Thảo Trinh. Batch TTS /
list_voicesare not restricted the same way.STT accepts WAV only. Convert with ffmpeg, e.g.:
ffmpeg -i input.mp3 -ar 16000 -ac 1 -sample_fmt s16 output.wavSupported sample rates: 8000/16000/22050/32000/44100/48000.
Sync TTS text limit: 300 characters. Batch TTS: 100,000 characters.
Sync STT file: < 10s, < 10MB. Batch STT: < 100MB.
audioLinkexpiry: 3 minutes. Audio retention: 3 days.
Error handling
Errors are raised as MCP tool errors with a stable code and message, mapped from the vbee API:
Code | HTTP | Meaning |
| 401 | Bad/missing App-Id or token |
| 400 | e.g. text > 300 chars, bad voiceCode, insufficient credit |
| 429 | Rate/quota limit reached |
| 500 | Credit spend failed |
| 500 | vbee internal error |
| — | Transport failure |
| — |
|
| — | Batch call without webhook |
Tokens are never logged or committed. .env is gitignored; only .env.example (with placeholders) is tracked. Note that .env is not read at runtime — export the variables or set them in your MCP client config.
Development
pip install -e '.[dev]'
pytest # unit tests; all HTTP is mocked, no live API calls
ruff check .Tương lai (not implemented in v1)
Streaming STT qua WebSocket (
/v1/stt/streaming, ~500ms) — cần MCP streaming/transport phù hợp.Voice cloning / PERSONAL voices, community voices.
AI Dubbing,
emphasis_intensity/client_pausenâng cao, pronunciation dictionary.Webhook receiver helper (local tunnel) để nhận callback cho batch.
Cache audio + auto-refresh
audioLinkquatts_get_request; retry/backoff cho 429.Đóng gói MCP resources (audio file), progress reporting, chọn mp3/wav theo use-case.
Publish lên MCP Hub / registry, Docker image,
uvxinstall.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Generate English and Chinese speech, split long text, track batch jobs, and download audio.
Text to speech, voice listing and phrase library search for AI assistants. API key header.
Speech-to-text, text-to-speech, OCR and typed decision-making APIs. Official site: https://suanlinfang.cn. New accounts get ¥10 free trial credit — create your API key: https://suanlinfang.cn/consume-web/api-keys.html
Vietnamese-first text to speech, photo and PDF tools, audio to text, QR codes. Free daily allowance.
Related MCP Servers
AlicenseAqualityCmaintenanceEnables AI agents to generate speech, transcribe audio, and manage voices via the Vocea API.6MIT- AlicenseAqualityFmaintenanceEnables text-to-speech conversion using ElevenLabs API with voice management, streaming support, and multiple models.51MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Vietnamese text-to-speech with voice cloning, 10 built-in voices, text normalization, and long-form queuing, running 100% locally.Apache 2.0
- AlicenseAqualityBmaintenanceText to speech in 149 languages: MP3 links from any assistant. Free without an account. 2,253 voices; PRO adds HD voices, WAV, dialogue with a voice per speaker, Script mode timing and transcription.750 npmMIT