Skip to main content
Glama

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

VBEE_APP_ID

yes

—

App ID from https://studio.vbee.vn/apps

VBEE_TOKEN

yes

—

API token (Bearer). Never commit it.

VBEE_API_BASE

no

https://api.vbee.vn

API base URL

VBEE_WEBHOOK_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_voices are 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.wav

    Supported 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.

  • audioLink expiry: 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

UNAUTHORIZED

401

Bad/missing App-Id or token

BAD_REQUEST

400

e.g. text > 300 chars, bad voiceCode, insufficient credit

TTS_CCR_MAX_LIMIT_REACHED

429

Rate/quota limit reached

TTS_SPEND_CREDITS_FAILED

500

Credit spend failed

INTERNAL_SERVER_ERROR

500

vbee internal error

NETWORK_ERROR

—

Transport failure

MISSING_CREDENTIALS

—

VBEE_APP_ID/VBEE_TOKEN not set

MISSING_WEBHOOK_URL

—

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_pause nâng cao, pronunciation dictionary.

  • Webhook receiver helper (local tunnel) để nhận callback cho batch.

  • Cache audio + auto-refresh audioLink qua tts_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, uvx install.

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