GPT-SoVITS

You enable GPT-SoVITS to run as an MCP server, exposing its speech synthesis and voice cloning capabilities to AI agents and client tools. This MCP server lets you manage models, stream audio, and coordinate voice profiles through a clean, documented API surface that integrates with Claude-like agents and other MCP clients.

How to use

You start the MCP server, then connect your MCP client to the HTTP MCP endpoint to access all tools. The server exposes an API documentation page, an MCP endpoint, and a health check so you can verify the service is running. Use the MCP client to call the available tools in real time: generate speech from text, switch models, adjust the reference voice, and control the server lifecycle. SSE-based or fetch-based MCP clients can subscribe to or fetch from the MCP endpoint as needed.

How to install

Prerequisites: you need Python 3.11 or newer. You also require the GPT-SoVITS API server running on port 9880.

# Windows
python -m pip install -r requirements.txt
cd GPT-SoVITS
python api.py

# Windows quick start for MCP
# Start the MCP server (fastapi_mcp_server.py) after the API server is running
python fastapi_mcp_server.py

For macOS or Linux, use Python 3.11 to install dependencies and start the servers:

# macOS/Linux
python3.11 -m pip install -r requirements.txt
cd GPT-SoVITS
python3.11 api.py

# Start the MCP server
python3.11 fastapi_mcp_server.py

If you prefer a simple start, you can use the provided start scripts once you have the servers configured.

Configuration and startup notes

Environment variables you can set to customize the MCP server behavior include the base path for voice files and the host/port the MCP server binds to. The defaults bind to 0.0.0.0:8000 and reference a voices directory if you use voice cloning.

{
  "mcpServers": {
    "gpt_sovits_http": {
      "type": "http",
      "name": "gpt_sovits_http",
      "url": "http://localhost:8000/mcp",
      "args": []
    }
  }
}

Endpoints and quick start

After starting, you can access:

• API Documentation: http://localhost:8000/docs
• MCP endpoint: http://localhost:8000/mcp
• Health check: http://localhost:8000/health

Security and maintenance notes

Keep the GPT-SoVITS API server up to date and ensure port 9880 for the GPT-SoVITS backend remains accessible from the MCP server. Use standard OS firewall rules to allow inbound connections to the MCP port (default 8000). Rotate credentials if you expose the MCP endpoint to external agents, and monitor the health endpoint to detect service degradation.

Available tools

text_to_speech

Synthesizes speech from text and supports voice cloning via a reference wav file in multiple formats (wav, ogg, aac).

set_model

Dynamically sets GPT/SoVITS model weights to switch between models without restarting the server.

set_reference

Configures the default reference voice and prompt text used for voice cloning.

control_server

Controls server lifecycle actions such as restart and shutdown.