Chatterbox MCP

🚀 Chatterbox TTS MCP Server

A simplified MCP server that offers text-to-speech generation with auto-playback using the Chatterbox TTS model. It loads the model on first use and provides real-time progress updates.

🚀 Quick Start

This MCP server simplifies the process of text-to-speech conversion. It exposes the Chatterbox TTS functionality through a streamlined tool, handling model loading, progress reporting, and audio playback seamlessly.

✨ Features

Single Tool: speak_text

The speak_text tool offers comprehensive text-to-speech capabilities:

• Parameters:

  • text (required): The text to be converted to speech.
  • exaggeration (optional): Controls expressiveness (ranging from 0.0 - 1.0, default is 0.5).
  • cfg_weight (optional): Controls classifier - free guidance (ranging from 0.0 - 1.0, default is 0.5).

• Features:

  • Automatically loads the model with progress notifications.
  • Generates speech using temporary files (with automatic cleanup).
  • Automatically plays audio on macOS using afplay.
  • Provides real - time progress updates during all phases:
    • Model initialization and loading.
    • Speech generation.
    • Audio playback.

Resource: chatterbox://model-info

Retrieve information about the TTS model status and device capabilities:

• Model loading status (loaded or not loaded).
• Device information (MPS/CUDA/CPU).
• Availability of hardware acceleration.

💻 Usage Examples

Basic Usage

Please use the speak_text tool to say "Hello, welcome to the Chatterbox TTS demonstration!"

Advanced Usage

Use speak_text to generate enthusiastic speech for "This is amazing!" with high expressiveness

The tool will automatically:

• Load the model if necessary (with progress updates).
• Generate the speech.
• Play the audio.
• Clean up temporary files.
• Provide status updates throughout the process.

📦 Installation

1. Install dependencies:

pip install mcp torch torchaudio

2. Install Chatterbox TTS: Follow the Chatterbox TTS installation instructions to ensure the chatterbox.tts module is available.

📚 Documentation

Configuration

Audio File Storage

By default, the server stores audio files in ~/.chatterbox/audio. You can configure a custom location:

Command line argument:

python chatterbox_mcp_server.py --audio-dir /path/to/custom/audio/directory

Environment variable:

export CHATTERBOX_AUDIO_DIR="/path/to/custom/audio/directory"
python chatterbox_mcp_server.py

Priority order:

1. Command line --audio-dir argument (highest priority).
2. CHATTERBOX_AUDIO_DIR environment variable.
3. Default: ~/.chatterbox/audio (lowest priority).

Audio File TTL (Time To Live)

By default, audio files are automatically cleaned up after 1 hour. You can configure a custom TTL:

Command line argument:

python chatterbox_mcp_server.py --audio-ttl-hours 24  # Keep files for 24 hours

Environment variable:

export CHATTERBOX_AUDIO_TTL_HOURS=24
python chatterbox_mcp_server.py

Priority order:

1. Command line --audio-ttl-hours argument (highest priority).
2. CHATTERBOX_AUDIO_TTL_HOURS environment variable.
3. Default: 1 hour (lowest priority).

Model Auto - Loading

By default, the TTS model is loaded on first use to minimize startup time. You can pre - load it at startup:

Command line argument:

python chatterbox_mcp_server.py --auto-load-model

This will load the model during server startup, which takes a few seconds but ensures the first TTS request is faster.

Audio Storage Features:

• Audio files are stored persistently with configurable automatic cleanup.
• Files are accessible via chatterbox://audio/{resource_id} resources.
• The directory is created automatically if it doesn't exist.
• Supports relative paths (will be expanded) and ~ home directory notation.

Running the Server

Standalone:

python chatterbox_mcp_server.py

With MCP tools:

mcp dev chatterbox_mcp_server.py

Integration with Claude Desktop

Add to your Claude Desktop MCP configuration:

Basic configuration:

{
  "mcpServers": {
    "chatterbox-tts": {
      "command": "python",
      "args": ["/path/to/chatterbox_mcp_server.py"],
      "env": {}
    }
  }
}

With custom configuration:

{
  "mcpServers": {
    "chatterbox-tts": {
      "command": "python",
      "args": [
        "/path/to/chatterbox_mcp_server.py", 
        "--audio-dir", "/custom/audio/path",
        "--auto-load-model",
        "--audio-ttl-hours", "24"
      ],
      "env": {
        "CHATTERBOX_AUDIO_DIR": "/custom/audio/path",
        "CHATTERBOX_AUDIO_TTL_HOURS": "24"
      }
    }
  }
}

🔧 Technical Details

Device Support

• Apple Silicon (M1/M2/M3/M4): Uses MPS acceleration when available.
• NVIDIA GPUs: Uses CUDA when available.
• CPU fallback: Works on any system.

Audio Processing

• Uses temporary files for audio storage.
• Automatically cleans up after playback.
• Outputs in WAV format.
• Generates high - quality audio.

Model Management

• The model loads once on first use.
• It is shared across all subsequent requests.
• Thread - safe loading with progress tracking.
• Automatically detects and optimizes the device.

File Structure

chatterbox-mcp/
├── chatterbox_mcp_server.py    # MCP server implementation
└── README.md                   # This documentation

Development

Key Improvements in This Version

1. Simplified Interface: Single speak_text tool instead of multiple tools.
2. Automatic Playback: No need to manually play generated files.
3. Progress Notifications: Real - time updates on model loading and generation.
4. Persistent Audio Storage: Audio files are stored with configurable automatic cleanup.
5. Better Error Handling: Comprehensive error reporting and recovery.
6. Streamlined Workflow: One command generates and plays speech.

Troubleshooting

Common Issues

1. Model loading slow:
   • First - time loading downloads model weights.
   • Progress notifications show current status.
   • Subsequent uses are much faster.
2. Audio playback issues:
   • afplay command is macOS - specific.
   • Ensure system audio is working.
   • Check volume settings.
3. Memory issues:
   • The model requires significant GPU/CPU memory.
   • Monitor system resources during loading.
   • Consider closing other applications.
4. Device selection:
   • The server automatically selects the best available device.
   • Check model info resource for the current device.
   • MPS (Apple Silicon) > CUDA (NVIDIA) > CPU.

📄 License

This MCP server implementation follows the same license as the underlying Chatterbox TTS model.