Bvoiz Help Center | Tài liệu hướng dẫn & Tích hợp API

Official MCP Server Repository

TraudioDev / bvoiz-mcp

Kho mã nguồn mở chính thức cung cấp máy chủ chuẩn Model Context Protocol (MCP) cho Bvoiz. Giúp các mô hình AI Agent (Claude, Codex, Antigravity, Cursor) tự động nhận diện giọng đọc, sinh âm thanh và lưu file trực tiếp vào máy tính của bạn.

1. Model Context Protocol (MCP) là gì?

Model Context Protocol (MCP) là tiêu chuẩn mở do Anthropic khởi xướng, cho phép các mô hình AI và môi trường phát triển (IDEs) kết nối an toàn với các dịch vụ và công cụ bên ngoài.

Thông qua Bvoiz MCP Server, bạn không cần phải tự viết mã gọi RESTful API hay xử lý lưu trữ tệp tin. Các trợ lý AI (Claude, Cursor, Antigravity...) sẽ được trang bị sẵn 14 công cụ nghiệp vụ để:

Sinh giọng nói AI: Đọc kịch bản tiếng Việt truyền cảm chuẩn studio.
Tự động lưu file cục bộ: Lưu ngay file MP3/WAV vào ổ cứng của dự án.
Thử giọng miễn phí: Thử nghiệm nhanh đến 300 ký tự không cần API Key.
Nhân bản giọng nói: Clone giọng cá nhân từ file mẫu 5-15s trên máy tính.

2. Cài đặt nhanh từ GitHub

Bạn chỉ cần clone repository từ GitHub và biên dịch bằng Node.js (phiên bản 18 trở lên):

Terminal / PowerShell

# 1. Clone repository chính thức về máy
git clone https://github.com/TraudioDev/bvoiz-mcp.git

# 2. Di chuyển vào thư mục dự án
cd bvoiz-mcp

# 3. Cài đặt thư viện phụ thuộc
npm install

# 4. Biên dịch mã nguồn TypeScript
npm run build

Sau khi build xong, file thực thi sẽ nằm tại đường dẫn: dist/index.js (ví dụ: E:\Git\bvoiz-mcp\dist\index.js).

3. Hướng dẫn cấu hình cho từng AI Agent

1Claude Desktop (Anthropic)

Mở file cấu hình Claude Desktop tại đường dẫn:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Thêm khối cấu hình Bvoiz vào thẻ mcpServers:

claude_desktop_config.json

{
  "mcpServers": {
    "bvoiz": {
      "command": "node",
      "args": ["E:\\Git\\bvoiz-mcp\\dist\\index.js"],
      "env": {
        "BVOIZ_API_KEY": "bv_live_your_actual_api_key_here"
      }
    }
  }
}

2Cursor AI Editor

Trong dự án của bạn, tạo file .cursor/mcp.json:

.cursor/mcp.json

{
  "mcpServers": {
    "bvoiz": {
      "command": "node",
      "args": ["E:\\Git\\bvoiz-mcp\\dist\\index.js"],
      "env": {
        "BVOIZ_API_KEY": "bv_live_your_actual_api_key_here"
      }
    }
  }
}

Hoặc vào Settings -> Features -> MCP Servers -> Add New MCP Server: Command: node E:\Git\bvoiz-mcp\dist\index.js.

3Claude Code (CLI)

Chạy lệnh thêm MCP trực tiếp bằng terminal:

Terminal

claude mcp add bvoiz node E:\Git\bvoiz-mcp\dist\index.js -e BVOIZ_API_KEY=bv_live_your_api_key

4Google Antigravity & Windsurf

Thêm vào cấu hình MCP server trong thiết lập Workspace hoặc ~/.gemini/antigravity/settings.json:

antigravity_config.json

{
  "mcpServers": {
    "bvoiz": {
      "command": "node",
      "args": ["E:\\Git\\bvoiz-mcp\\dist\\index.js"],
      "env": {
        "BVOIZ_API_KEY": "bv_live_your_actual_api_key_here"
      }
    }
  }
}

4. Danh mục 14 MCP Tools có sẵn

Tool Name	Mục đích	Tính năng nổi bật
bvoiz_synthesize_speech	Chuyển văn bản thành giọng nói (TTS)	Hỗ trợ `save_to_file` tự động lưu audio về máy tính, chỉnh speed, pitch, mp3/wav
bvoiz_demo_synthesize	Thử giọng miễn phí	Không cần API Key, không tốn credits (tối đa 300 ký tự)
bvoiz_list_voices	Danh sách giọng đọc	Lọc theo vùng miền (Bắc/Trung/Nam), giới tính, nhà cung cấp, giọng phổ biến
bvoiz_search_voices	Tìm kiếm giọng thông minh	Tìm theo từ khóa (tin tức, podcast, review phim, TVC quảng cáo, hào sảng)
bvoiz_get_voice_details	Xem chi tiết giọng đọc	Lấy mô tả chi tiết, liên kết nghe thử audio mẫu theo ID giọng
bvoiz_clone_voice	Nhân bản giọng nói mới	Huấn luyện giọng riêng từ file âm thanh 5-15s trên máy tính
bvoiz_list_cloned_voices	Danh sách giọng clone	Xem toàn bộ giọng nói nhân bản trong tài khoản
bvoiz_test_cloned_voice	Đọc thử giọng clone	Kiểm tra chất lượng giọng nhân bản với câu thử nghiệm
bvoiz_delete_cloned_voice	Xóa giọng nhân bản	Xóa giọng clone không còn sử dụng
bvoiz_download_audio	Tải file âm thanh	Tải audio từ Bvoiz về đường dẫn ổ cứng mong muốn
bvoiz_get_job_status	Kiểm tra tiến độ tác vụ	Hỗ trợ `wait_until_complete: true` tự động chờ đến khi xong
bvoiz_get_account	Thông tin tài khoản	Xem số dư credits còn lại, email, vai trò và trạng thái tài khoản
bvoiz_get_history	Lịch sử tạo audio	Tra cứu các lần tạo âm thanh gần đây
bvoiz_get_pricing_plans	Bảng giá & VietQR	Tra cứu gói cước và hướng dẫn nạp credits qua VietQR Napas 247

5. Câu lệnh mẫu (Prompt) bạn có thể ra lệnh cho AI

Dựng Voiceover video tự động:

"Hãy viết kịch bản 30 giây giới thiệu sản phẩm phần mềm mới, sau đó dùng Bvoiz giọng nữ miền Nam sang trọng (Ngân Nguyễn) đọc và lưu file vào ./assets/voiceover.mp3 cho tôi."

Thử giọng miễn phí không tốn credit:

"Tìm cho tôi giọng nam miền Bắc phong cách hào sảng để làm video lịch sử, sau đó đọc thử câu chào bằng công cụ bvoiz_demo_synthesize."

Nhân bản giọng từ file máy tính:

"Tôi có file thu âm mẫu ở E:/my_sample.wav. Hãy dùng Bvoiz tạo giọng nhân bản tên Giọng Cá Nhân và đọc thử thông báo hoàn thành dự án."

Khám phá kho mã nguồn Bvoiz MCP

Mã nguồn mở chuẩn TypeScript, sẵn sàng đóng góp và tích hợp vào hệ thống của bạn.

https://github.com/TraudioDev/bvoiz-mcp.git