Content
# TTS MCP Server
Text-to-Speech MCP (Model Context Protocol) server. Supports various TTS services with adapter pattern.
## Supported TTS Services
- **Typecast** - [Neosapience](https://typecast.ai/) TTS API
## Installation
```bash
npm install
npm run build
```
## Environment Variables
Create a `.env` file:
```env
TYPECAST_API_KEY=your_api_key_here
```
## Connecting to Claude Code
```bash
claude mcp add tts-mcp -t stdio -s user \
-e TYPECAST_API_KEY=your_api_key \
-- node /path/to/tts-mcp/dist/index.js
```
## Tools
### `tts_synthesize`
Converts text to a voice file.
**Parameters:**
| Parameter | Required | Description |
|---------|:----:|------|
| `text` | ✅ | Text to be synthesized |
| `voice_id` | ✅ | Voice ID (e.g., `tc_xxx`) |
| `model_id` | ❌ | Model ID (default: `ssfm-v21`) |
| `adapter` | ❌ | TTS adapter (default: `typecast`) |
| `options` | ❌ | Additional options (see below) |
**Options:**
| Option | Type | Description |
|-----|------|------|
| `emotion` | string | Emotion preset (`normal`, `happy`, `sad`, etc.) |
| `emotion_intensity` | number | Emotion intensity (0.0 ~ 2.0) |
| `volume` | number | Volume (0 ~ 200, default: 100) |
| `pitch` | number | Pitch adjustment (-12 ~ 12) |
| `tempo` | number | Tempo adjustment (0.5 ~ 2.0) |
| `format` | string | Output format (`mp3` or `wav`) |
| `outputDir` | string | Output directory |
| `outputName` | string | Output file name (without extension) |
**Response:**
```json
{
"filePath": "/path/to/output.mp3",
"duration": 3.5,
"format": "mp3"
}
```
### `tts_list_voices`
Retrieves a list of available voices.
**Parameters:**
| Parameter | Required | Description |
|---------|:----:|------|
| `adapter` | ❌ | TTS adapter (default: `typecast`) |
| `model_id` | ❌ | Model ID |
**Response:**
```json
[
{
"id": "tc_xxx",
"name": "Voice Name",
"model": "ssfm-v21",
"emotions": ["normal", "happy", "sad"]
}
]
```
## Usage Examples
### Using Claude Code
```
# List available voices
"Show me the list of voices available on typecast"
# Generate TTS
"Convert 'Hello' to tc_xxx voice"
# With options
"Convert 'Hello' to happy emotion and tempo 1.2 and save to /output folder"
```
## Adapter Extension
To add a new TTS service, implement the `TTSAdapter` interface:
```typescript
// src/adapters/my-tts.ts
import type { TTSAdapter, TTSOptions, TTSResult, Voice } from './base.js';
export class MyTTSAdapter implements TTSAdapter {
readonly name = 'my-tts';
async synthesize(
text: string,
voiceId: string,
modelId: string,
options?: TTSOptions
): Promise<TTSResult> {
// Implementation
}
async getVoices(modelId?: string): Promise<Voice[]> {
// Implementation
}
}
```
And register the adapter in `src/index.ts`:
```typescript
import { MyTTSAdapter } from './adapters/my-tts.js';
const adapters: Record<string, TTSAdapter> = {
typecast: new TypecastAdapter(TYPECAST_API_KEY),
'my-tts': new MyTTSAdapter(API_KEY),
};
```
## Running with PM2
```bash
pm2 start ecosystem.config.cjs
```
## License
MIT
