Metadata-Version: 2.4
Name: superclonica-mcp
Version: 0.1.1
Summary: Local MCP server for SuperClonica text to speech: offline voices in 31 languages, no limits, voices from superclonica.com
Author: superclonica.com
License-Expression: Apache-2.0
Project-URL: Homepage, https://superclonica.com/
Project-URL: API keys, https://superclonica.com/speech-api
Keywords: mcp,model-context-protocol,tts,text-to-speech,supertonic,superclonica,offline
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: mcp<3,>=2.3
Requires-Dist: superclonica-cpu>=0.6.25
Requires-Dist: soundfile>=0.13
Requires-Dist: numpy>=1.26
Requires-Dist: truststore>=0.10
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# SuperClonica MCP server

<!-- mcp-name: io.github.superclonica-tts/superclonica-mcp -->

Text to speech for Claude and other MCP clients, running on your own computer: offline after the first run, no limits, 31 languages. It is the local sibling of the cloud server at `https://superclonica.com/mcp`, with the same tool names. Voices come from the [SuperClonica catalog](https://superclonica.com/).

Works on Windows, macOS and Linux with Python 3.10 or newer. Chinese is not supported.

## Set it up

You need [uv](https://docs.astral.sh/uv/getting-started/installation/), which gives the `uvx` command. The first start installs the engine, which takes a minute or two. The first `speak` downloads the voice model (about 400 MB) once.

**Claude Desktop.** Add this to `claude_desktop_config.json` and restart the app:

```json
{
  "mcpServers": {
    "superclonica": {
      "command": "uvx",
      "args": ["superclonica-mcp"],
      "env": { "SUPERCLONICA_API_KEY": "sc_..." }
    }
  }
}
```

If the app cannot find `uvx`, put the full path to it in `command`. On Windows `where uvx` prints it, on macOS and Linux `which uvx`.

**Claude Code:**

```bash
claude mcp add superclonica -e SUPERCLONICA_API_KEY=sc_... -- uvx superclonica-mcp
```

**Cursor** (`~/.cursor/mcp.json`) takes the same JSON as Claude Desktop. **VS Code** (`.vscode/mcp.json`) takes the same entry under `"servers"`, with `"type": "stdio"` added.

Without `uvx`, these start the same server: `pipx run superclonica-mcp`, or `python -m superclonica_mcp` after `pip install superclonica-mcp`.

The API key is optional. Stock and free catalog voices need none. Installing a bought or your own voice does; [creating a key](https://superclonica.com/speech-api) is free.

## Tools

| Tool | What it does |
|---|---|
| `list_voices(query?, limit?)` | Voices on this computer and, when online, the catalog. Shows for each whether it is installed, yours, free or must be bought, with its page. |
| `speak(text, voice, language, format?, output_path?, include_audio?)` | Voices the text on this computer and saves mp3, wav or ogg. Gives the file's path and length, and the audio itself if asked. Up to 20000 characters per call. An existing file is never overwritten. |
| `install_voice(voice)` | Downloads a voice you may use to this computer. A version you already have is not downloaded again. |
| `buy_voice(voice)` | Gives the link to the voice's page. **It never pays:** you buy in your browser, then tell the assistant to install it. |
| `play(path)` | Plays an mp3, wav or ogg file with the system player. |
| `get_usage()` | Whether the model is loaded and on what device, and which folders are used. The local engine has no limits. |

`voice` is an id from `list_voices`, a stock name (`F1`–`F5`, `M1`–`M5`) or an exact name. When a name fits several voices you get the candidates to choose from, never a guess.

To use your own voice file, put its JSON in the voices folder. It goes by its file name.

## Buying a voice

1. Ask for a voice, for example "find a calm narrator". The assistant calls `list_voices`.
2. If it must be bought, the assistant calls `buy_voice` and gives you a link that opens the purchase window.
3. Confirm the purchase in your browser. Only your click can buy.
4. Say "install it". After that the voice works offline.

## Settings

All are optional environment variables.

| Variable | Meaning | Default |
|---|---|---|
| `SUPERCLONICA_API_KEY` | Key for installing bought and your own voices | none |
| `SUPERCLONICA_VOICES_DIR` | Folder of voices | Windows `%APPDATA%\SuperClonica\voices`; macOS `~/Library/Application Support/SuperClonica/voices`; Linux `~/.local/share/superclonica/voices` |
| `SUPERCLONICA_OUTPUT_DIR` | Folder for audio | `audio` beside the voices folder |
| `SUPERCLONICA_DEVICE` | `cpu` or `gpu` | GPU if the GPU engine is installed, else CPU |

## Faster on an NVIDIA GPU

`uvx superclonica-mcp` installs the CPU engine, and the CPU and GPU engines cannot share one environment. For the GPU engine (Windows or Linux x86-64, Python 3.11+), make an environment of its own:

```bash
uv venv superclonica-gpu --python 3.12
uv pip install --python superclonica-gpu superclonica-gpu-cuda
uv pip install --python superclonica-gpu --no-deps superclonica-mcp
uv pip install --python superclonica-gpu "mcp>=2.3,<3" "truststore>=0.10"
```

Then use the Python of that environment as the command, with `-m superclonica_mcp` as the arguments and `SUPERCLONICA_DEVICE=gpu` in `env`.

## When something goes wrong

- **"The voice model is still loading":** the first run is downloading the model, and that goes on in the background. Ask again in a minute.
- **The client shows no tools:** look at the server's log (Claude Desktop: *Settings → Developer*). The server writes its log only to stderr.
- **A long text times out:** on a CPU, voice long texts in parts.

## License

Apache-2.0. The voice model is Supertonic 3 under its own OpenRAIL-M license, downloaded from its original place by the engine.
