Fish Audio MCP Server

An MCP (Model Context Protocol) server that provides seamless integration between Fish Audio's Text-to-Speech API and LLMs like Claude, enabling natural language-driven speech synthesis.

What is Fish Audio?

Fish Audio is a cutting-edge Text-to-Speech platform that offers:

• 🌊 State-of-the-art voice synthesis with natural-sounding output

• 🎯 Voice cloning capabilities to create custom voice models

• 🌍 Multilingual support including English, Japanese, Chinese, and more

• ⚡ Low-latency streaming for real-time applications

• 🎨 Fine-grained control over speech prosody and emotions

This MCP server brings Fish Audio's powerful capabilities directly to your LLM workflows.

Features

• 🎙️ High-Quality TTS: Leverage Fish Audio's state-of-the-art TTS models

• 🌊 Streaming Support: Real-time audio streaming for low-latency applications

• 🎨 Multiple Voices: Support for custom voice models via reference IDs

• 🎯 Smart Voice Selection: Select voices by ID, name, or tags

• 📚 Voice Library Management: Configure and manage multiple voice references

• 🔧 Flexible Configuration: Environment variable-based configuration

• 📦 Multiple Audio Formats: Support for MP3, WAV, PCM, and Opus

• 🚀 Easy Integration: Simple setup with any MCP-compatible client

Quick Start

Installation

You can run this MCP server directly using npx:

Or install it globally:

Configuration

1. Get your Fish Audio API key from Fish Audio

2. Set up environment variables:

3. Add to your MCP settings configuration:

Single Voice Mode (Simple)

Multiple Voice Mode (Advanced)

Environment Variables

Configuring Multiple Voice References

You can configure multiple voice references in two ways:

JSON Array Format (Recommended)

Use the FISH_REFERENCES environment variable with a JSON array:

Individual Format (Backward Compatibility)

Use numbered environment variables:

Usage

Once configured, the Fish Audio MCP server provides two tools to LLMs.

Tool 1: fish_audio_tts

Generates speech from text using Fish Audio's TTS API.

Parameters

• text (required): Text to convert to speech (max 10,000 characters)

• reference_id (optional): Voice model reference ID

• reference_name (optional): Select voice by name

• reference_tag (optional): Select voice by tag

• streaming (optional): Enable streaming mode

• format (optional): Output format (mp3, wav, pcm, opus)

• mp3_bitrate (optional): MP3 bitrate (64, 128, 192)

• normalize (optional): Enable text normalization (default: true)

• latency (optional): Latency mode (normal, balanced)

• output_path (optional): Custom output file path

• auto_play (optional): Automatically play the generated audio

• websocket_streaming (optional): Use WebSocket streaming instead of HTTP

• realtime_play (optional): Play audio in real-time during WebSocket streaming

Voice Selection Priority: reference_id > reference_name > reference_tag > default

Tool 2: fish_audio_list_references

Lists all configured voice references.

Parameters

No parameters required.

Returns

• List of configured voice references with their IDs, names, and tags

• Default reference ID

Examples

Basic Text-to-Speech

Using Custom Voice by ID

Using Voice by Name

Using Voice by Tag

List Available Voices

HTTP Streaming Mode

WebSocket Real-time Streaming

Development

Local Development

1. Clone the repository:

2. Install dependencies:

3. Create .env file:

4. Build the project:

5. Run in development mode:

Testing

Run the test suite:

Project Structure

API Documentation

Fish Audio Service

The service provides two main methods:

1. generateSpeech: Standard TTS generation

   • Returns audio buffer

   • Suitable for short texts

   • Lower memory usage

2. generateSpeechStream: Streaming TTS generation

   • Returns audio stream

   • Suitable for long texts

   • Real-time processing

Error Handling

The server handles various error scenarios:

• INVALID_API_KEY: Invalid or missing API key

• NETWORK_ERROR: Connection issues with Fish Audio API

• INVALID_PARAMS: Invalid request parameters

• QUOTA_EXCEEDED: API rate limit exceeded

• SERVER_ERROR: Fish Audio server errors

Troubleshooting

Common Issues

1. "FISH_API_KEY environment variable is required"

   • Ensure you've set the FISH_API_KEY environment variable

   • Check that the API key is valid

2. "Network error: Unable to reach Fish Audio API"

   • Check your internet connection

   • Verify Fish Audio API is accessible

   • Check for proxy/firewall issues

3. "Text length exceeds maximum limit"

   • Split long texts into smaller chunks

   • Maximum supported length is 10,000 characters

4. Audio files not appearing

   • Check the AUDIO_OUTPUT_DIR path exists

   • Ensure write permissions for the directory

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/AmazingFeature)

3. Commit your changes (git commit -m 'Add some AmazingFeature')

4. Push to the branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Fish Audio for providing the excellent TTS API

• Anthropic for creating the Model Context Protocol

• The MCP community for inspiration and examples

Support

For issues, questions, or contributions, please visit the GitHub repository.

Changelog

See CHANGELOG.md for a detailed list of changes.