Metadata-Version: 2.4
Name: voicestudio-mcp
Version: 0.1.0
Summary: MCP server for Voice Studio — text-to-speech, voice cloning, voice design, transcription, and music generation as agent tools.
Project-URL: Homepage, https://aiaudiogen.com
Project-URL: Repository, https://github.com/aiworkmagic/voicestudio
Project-URL: Issues, https://github.com/aiworkmagic/voicestudio/issues
Author: Voice Studio
License: MIT
Keywords: mcp,music,speech,tts,voice-cloning,voice-studio
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Description-Content-Type: text/markdown

# voicestudio-mcp

An MCP (Model Context Protocol) server that lets agents drive
[Voice Studio](https://aiaudiogen.com) - a local desktop app for
text-to-speech, voice cloning, voice design, transcription, and music
generation. Once installed, Claude Desktop, Claude Code, Cursor, and any
other MCP-aware client gets 12 audio tools that talk to the Voice Studio
backend running on your machine.

## Requirements

- Voice Studio.app installed (download from https://aiaudiogen.com)
- Python 3.11+ (only needed if installing via `pip` - `uvx` ships its own)

The MCP server will auto-launch the Voice Studio app the first time you
call a tool, then poll until the local backend is ready.

## Install

### Option A - `uvx` (recommended)

No global install. Each MCP client launches it on demand:

```bash
uvx voicestudio-mcp
```

### Option B - `pip`

```bash
pip install voicestudio-mcp
voicestudio-mcp   # runs the stdio server (Ctrl+C to exit)
```

### Option C - local checkout

```bash
cd voicestudio-app/integrations/mcp_server
pip install -e .
```

## Wire it into your MCP client

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and
add:

```json
{
  "mcpServers": {
    "voicestudio": {
      "command": "uvx",
      "args": ["voicestudio-mcp"]
    }
  }
}
```

If you used `pip install` instead of `uvx`:

```json
{
  "mcpServers": {
    "voicestudio": {
      "command": "voicestudio-mcp"
    }
  }
}
```

Restart Claude Desktop. The 12 `vs_*` tools will appear in the tool
palette.

### Claude Code

```bash
claude mcp add voicestudio uvx voicestudio-mcp
```

Or by editing `.claude/mcp_config.json` in your project:

```json
{
  "mcpServers": {
    "voicestudio": {
      "command": "uvx",
      "args": ["voicestudio-mcp"]
    }
  }
}
```

## Tools

| Tool                          | What it does                                                                  |
| ----------------------------- | ----------------------------------------------------------------------------- |
| `vs_list_voices`              | List built-in voices and your custom cloned profiles.                         |
| `vs_generate_speech`          | Text-to-speech with a built-in voice. Returns a WAV file path.                |
| `vs_generate_with_profile`    | Text-to-speech using one of your saved cloned voices.                         |
| `vs_clone_voice`              | Clone a voice from a reference recording (mp3/wav).                           |
| `vs_design_voice`             | Generate speech with a voice synthesized from a free-form description.        |
| `vs_transcribe`               | Transcribe an audio file via NeMo ASR.                                        |
| `vs_generate_music`           | Generate royalty-free music from a text prompt (5-30s).                       |
| `vs_list_history`             | Recent generations from the Voice Studio library.                             |
| `vs_download_from_history`    | Re-save a past generation by its history record id.                           |
| `vs_license_status`           | Check Voice Studio license status (active / inactive / trial).                |
| `vs_free_models`              | Free all loaded ML models from memory.                                        |
| `vs_current_service`          | Which ML service is currently loaded (tts/clone/design/asr/music/none).       |

## Notes

- **Audio is returned as file paths, not inline bytes.** Generated WAVs
  can be 500 KB to several MB; we hand back the absolute path plus a
  one-line summary. Default output directory is
  `~/Documents/VoiceStudio/integrations-out/` (override with
  `VS_OUTPUT_DIR`).
- **One ML pipeline at a time.** Voice Studio loads one model into
  memory at any moment. Calling `vs_generate_speech` then
  `vs_generate_music` back-to-back will incur a model-swap latency
  while the first model unloads and the second loads.
- **Auto-launch.** If Voice Studio isn't running when you call a tool,
  the server spawns it and waits up to 45 seconds for the backend to
  answer `/health` (override with `VS_LAUNCH_TIMEOUT`).
- **Backend port.** Defaults to `127.0.0.1:58391`. Override with
  `VS_BACKEND_HOST` and `VS_BACKEND_PORT`.

## License

MIT
