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.

---

Requirements

Component	Requirement
MCP server	Python 3.10+, mcp>=1.0.0
Worker (CUDA venv)	Python 3.12, torch 2.x + CUDA 12.x, voxcpm, soundfile, numpy
GPU	NVIDIA GPU with ≥ 6 GB VRAM (tested on RTX 4060 Laptop)
Model	openbmb/VoxCPM2 cached in Hugging Face local cache

---

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

Tool	Description
synthesize	Text → WAV using default VoxCPM2 voice
synthesize_with_clone	Text → WAV cloning a reference speaker voice
preload_model	Load model into VRAM (warm-up, ~10 s)
ping	Check worker subprocess health

synthesize parameters

Parameter	Type	Default	Description
text	string	required	Text to synthesize
output_filename	string	output.wav	Output filename inside VOXCPM_OUTPUT_DIR
steps	integer	30	Diffusion steps (10=fast draft, 50=best quality)

synthesize_with_clone parameters

Parameter	Type	Default	Description
text	string	required	Text to synthesize
reference_wav_path	string	required	Absolute path to reference WAV (48 kHz mono)
reference_text	string	required	Transcript of the reference WAV
output_filename	string	cloned.wav	Output filename
steps	integer	30	Diffusion steps

---

/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

Variable	Default	Description
VOXCPM_PYTHON	...fraudsentinel...\.venv312\Scripts\python.exe	Python executable with VoxCPM2 + CUDA
VOXCPM_OUTPUT_DIR	./voxcpm_output	Directory where WAV files are saved

---

License

MIT — see LICENSE.