# 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

```bash
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:

```bash
# 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)

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

### 4. Register with Claude Code

```bash
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:

```bash
# 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](LICENSE).