MCP FishAudio Server

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

v0.6.0 (2025-01-03)

• Added multiple voice reference management system
• New tool: fish_audio_list_references to list configured voices
• Voice selection by name or tag in addition to ID
• Support for configuring multiple voices with metadata
• Added FISH_REFERENCES and FISH_DEFAULT_REFERENCE environment variables
• Enhanced voice selection with priority: ID > Name > Tag > Default

v0.5.4 (2025-01-03)

• Fixed zod version compatibility issues
• Resolved dependency conflicts between MCP SDK and Fish Audio SDK
• Verified local dev and build functionality

v0.5.3 (2025-01-03)

• Fixed missing zod dependency causing module resolution errors
• Improved compatibility when running via npx

v0.5.2 (2025-01-03)

• Fixed audio playback issue with FISH_STREAMING=true
• Fixed tilde (~) expansion in AUDIO_OUTPUT_DIR
• Improved stability by separating HTTP and WebSocket streaming

v0.5.1 (2025-01-03)

• Improved documentation formatting and clarity
• Updated environment variables table for better readability
• Made documentation more generic for all MCP clients

v0.5.0 (2025-01-03)

• Simplified environment variables: removed FISH_WEBSOCKET_STREAMING and FISH_REALTIME_PLAY
• WebSocket streaming now controlled by FISH_STREAMING
• Real-time playback now controlled by FISH_AUTO_PLAY
• Cleaner configuration with unified controls

v0.4.1 (2025-01-03)

• Added intelligent environment variable mapping
• FISH_WEBSOCKET_STREAMING defaults to FISH_STREAMING
• FISH_REALTIME_PLAY defaults to FISH_AUTO_PLAY
• Simplified configuration with smart defaults

v0.4.0 (2025-01-03)

• Refactored to use official Fish Audio SDK
• Improved WebSocket streaming implementation
• Fixed auto-play functionality
• Better error handling and connection stability
• Latency parameter now properly supported (normal/balanced)
• Cleaner codebase with SDK integration

v0.3.0 (2025-01-03)

• Added WebSocket streaming support for real-time TTS
• Added real-time audio playback during WebSocket streaming
• New parameters: websocket_streaming and realtime_play
• Support for both HTTP and WebSocket streaming modes
• Real-time player for immediate audio output

v0.2.0 (2025-01-03)

• Added automatic audio playback feature with auto_play parameter
• Added FISH_AUTO_PLAY environment variable for default behavior
• Support for cross-platform audio playback (macOS, Windows, Linux)
• HTTP streaming mode implementation

v0.1.2 (2025-01-03)

• Changed npm package name to @alanse/fish-audio-mcp-server

v0.1.1 (2025-01-03)

• Fixed directory creation error when running via npx
• Changed default audio output to user's home directory

v0.1.0 (2025-01-03)

• Initial release
• Basic TTS functionality
• Streaming support
• Environment variable configuration
• Multiple audio format support