# Voicebox MCP (Full)

Full-control MCP server for the locally-hosted **Voicebox** TTS / voice-cloning app.
Exposes **102 tools** over the Voicebox REST API (`http://127.0.0.1:17493`).

## Tool summary (102 total)

- Speech Generation (12): `voicebox_generate`, `voicebox_transcribe`, `voicebox_wait_for_generation`, …
- Voice Profiles & Cloning (18): `voicebox_create_profile`, `voicebox_add_sample`, …
- Stories / Audio Projects (11): `voicebox_create_story`, `voicebox_edit_story_item`, …
- Model Management (10): `voicebox_load_model`, `voicebox_download_model`, …  
  Note: `voicebox_get_migrate_progress` can hang due to SSE streaming.
- Channels (6): `voicebox_create_channel`, `voicebox_set_channel_voices`, …
- History & Audio Retrieval (14): `voicebox_list_history`, `voicebox_save_audio`, …  
  Note: `voicebox_list_failed_generations` is flaky (Voicebox API routing bug).
- Effects (8): `voicebox_apply_effects`, `voicebox_create_effect_preset`, …
- Captures & Transcription (7): `voicebox_get_capture`, `voicebox_refine_capture`, …
- System (16): `voicebox_get_health`, `voicebox_get_active_tasks`, …

Full agent guide: [`AGENT_TOOLS.md`](AGENT_TOOLS.md)

## Install

```powershell
git clone https://github.com/valentinlutun-cmd/voicebox-mcp-full.git
cd voicebox-mcp-full
pip install -e .
```

## Cursor / MCP config

```json
{
  "mcpServers": {
    "voicebox": {
      "command": "voicebox-mcp-full",
      "env": {
        "VOICEBOX_URL": "http://127.0.0.1:17493"
      }
    }
  }
}
```

Or:

```json
{
  "mcpServers": {
    "voicebox": {
      "command": "python",
      "args": ["-m", "voicebox_mcp.server"],
      "env": {
        "VOICEBOX_URL": "http://127.0.0.1:17493"
      }
    }
  }
}
```

Voicebox must be running locally.