voxcpm-mcp

VoxCPM2 diffusion TTS as an MCP server for Claude Code.
Synthesize speech, clone voices, and narrate anything — from inside Claude Code with a /voxcpm slash command.

VoxCPM2 is a 2B-parameter diffusion text-to-speech model by OpenBMB that produces 48 kHz speech with expressive prosody and accurate voice cloning. This package wraps it in an MCP server so Claude Code (or any MCP client) can call it as a tool.

Architecture

Claude Code (MCP client)
        │  stdio MCP
        ▼
voxcpm-mcp server (any Python ≥ 3.10)
        │  subprocess stdin/stdout JSON
        ▼
worker.py  (runs inside CUDA venv — torch + voxcpm installed)
        │
VoxCPM2 model (openbmb/VoxCPM2, loaded once, stays in VRAM)

The server and CUDA worker are deliberately separated so the MCP server itself has zero heavy dependencies — only mcp. The CUDA venv (with torch, voxcpm, soundfile, etc.) is pointed to via VOXCPM_PYTHON.

Related MCP server: Voice MCP

Requirements

Installation

1. Install the MCP server package

pip install -e .
# or, without cloning:
pip install git+https://github.com/OLGTX303/voxcpm-mcp.git

2. Point to your CUDA venv

Set VOXCPM_PYTHON to the Python executable inside a venv that has voxcpm and torch+CUDA installed:

# Windows
set VOXCPM_PYTHON=C:\path\to\cuda-venv\Scripts\python.exe

# Linux / macOS
export VOXCPM_PYTHON=/path/to/cuda-venv/bin/python

If you used the fraudsentinel demo tools setup, the venv is already at:

F:\5Gcase\hackton\fraudsentinel\demotools\fraudsentinel-demo\.venv312\Scripts\python.exe

3. Download VoxCPM2 model (if not already cached)

from huggingface_hub import snapshot_download
snapshot_download("openbmb/VoxCPM2")

4. Register with Claude Code

claude mcp add voxcpm-tts \
  -e VOXCPM_PYTHON="C:\path\to\cuda-venv\Scripts\python.exe" \
  -e VOXCPM_OUTPUT_DIR="C:\path\to\output" \
  -- voxcpm-mcp

5. Install the /voxcpm skill

Copy the skill file to your Claude Code commands directory:

# Windows
copy .claude\commands\voxcpm.md %APPDATA%\Claude\commands\voxcpm.md

# Linux / macOS
cp .claude/commands/voxcpm.md ~/.claude/commands/voxcpm.md

Or place it in your project's .claude/commands/ folder to make it project-local.

MCP tools

synthesize parameters

synthesize_with_clone parameters

/voxcpm skill

Once installed, use the slash command in Claude Code:

/voxcpm Welcome to the demonstration of autonomous forensic incident response.

/voxcpm Clone my voice from ref.wav — it says "Hello world". Now say: Good morning.

/voxcpm warm up

Environment variables

License

MIT — see LICENSE.