Skip to main content
Glama

MCP FishAudio Server

by da-okazaki

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.

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
  • 🔧 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:

npx @alanse/fish-audio-mcp-server

Or install it globally:

npm install -g @alanse/fish-audio-mcp-server

Configuration

  1. Get your Fish Audio API key from Fish Audio
  2. Set up environment variables:
export FISH_API_KEY=your_fish_audio_api_key_here
  1. Add to your MCP settings configuration:
{ "mcpServers": { "fish-audio": { "command": "npx", "args": ["-y", "@alanse/fish-audio-mcp-server"], "env": { "FISH_API_KEY": "your_fish_audio_api_key_here", "FISH_MODEL_ID": "s1", "FISH_REFERENCE_ID": "your_voice_reference_id_here", "FISH_OUTPUT_FORMAT": "mp3", "FISH_STREAMING": "false", "FISH_LATENCY": "balanced", "FISH_MP3_BITRATE": "128", "FISH_AUTO_PLAY": "false", "AUDIO_OUTPUT_DIR": "~/.fish-audio-mcp/audio_output" } } } }

Environment Variables

VariableDescriptionDefaultRequired
FISH_API_KEYYour Fish Audio API key-Yes
FISH_MODEL_IDTTS model to use (s1, speech-1.5, speech-1.6)s1Optional
FISH_REFERENCE_IDDefault voice reference ID-Optional
FISH_OUTPUT_FORMATDefault audio format (mp3, wav, pcm, opus)mp3Optional
FISH_STREAMINGEnable streaming mode (HTTP/WebSocket)falseOptional
FISH_LATENCYLatency mode (normal, balanced)balancedOptional
FISH_MP3_BITRATEMP3 bitrate (64, 128, 192)128Optional
FISH_AUTO_PLAYAuto-play audio and enable real-time playbackfalseOptional
AUDIO_OUTPUT_DIRDirectory for audio file output~/.fish-audio-mcp/audio_outputOptional

Usage

Once configured, the Fish Audio MCP server provides the fish_audio_tts tool to LLMs.

Tool: 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
  • 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

Examples

Basic Text-to-Speech
User: "Generate speech saying 'Hello, world! Welcome to Fish Audio TTS.'" Claude: I'll generate speech for that text using Fish Audio TTS. [Uses fish_audio_tts tool with text parameter] Result: Audio file saved to ./audio_output/tts_2025-01-03T10-30-00.mp3
Using Custom Voice
User: "Generate speech with voice model xyz123 saying 'This is a custom voice test'" Claude: I'll generate speech using the specified voice model. [Uses fish_audio_tts tool with text and reference_id parameters] Result: Audio generated with custom voice model xyz123
HTTP Streaming Mode
User: "Generate a long speech in streaming mode about the benefits of AI" Claude: I'll generate the speech in streaming mode for faster response. [Uses fish_audio_tts tool with streaming: true] Result: Streaming audio saved to ./audio_output/tts_2025-01-03T10-35-00.mp3
WebSocket Real-time Streaming
User: "Stream and play in real-time: 'Welcome to the future of AI'" Claude: I'll stream the speech via WebSocket and play it in real-time. [Uses fish_audio_tts tool with websocket_streaming: true, realtime_play: true] Result: Audio streamed and played in real-time via WebSocket

Development

Local Development

  1. Clone the repository:
git clone https://github.com/da-okazaki/mcp-fish-audio-server.git cd mcp-fish-audio-server
  1. Install dependencies:
npm install
  1. Create .env file:
cp .env.example .env # Edit .env with your API key
  1. Build the project:
npm run build
  1. Run in development mode:
npm run dev

Testing

Run the test suite:

npm test

Project Structure

mcp-fish-audio-server/ ├── src/ │ ├── index.ts # MCP server entry point │ ├── tools/ │ │ └── tts.ts # TTS tool implementation │ ├── services/ │ │ └── fishAudio.ts # Fish Audio API client │ ├── types/ │ │ └── index.ts # TypeScript definitions │ └── utils/ │ └── config.ts # Configuration management ├── tests/ # Test files ├── audio_output/ # Default audio output directory ├── package.json ├── tsconfig.json └── README.md

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.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
-
security - not tested
A
license - permissive license
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

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.

  1. Features
    1. Quick Start
      1. Installation
      2. Configuration
    2. Environment Variables
      1. Usage
        1. Tool: fish_audio_tts
        2. Examples
      2. Development
        1. Local Development
        2. Testing
        3. Project Structure
      3. API Documentation
        1. Fish Audio Service
        2. Error Handling
      4. Troubleshooting
        1. Common Issues
      5. Contributing
        1. License
          1. Acknowledgments
            1. Support
              1. Changelog
                1. v0.5.4 (2025-01-03)
                2. v0.5.3 (2025-01-03)
                3. v0.5.2 (2025-01-03)
                4. v0.5.1 (2025-01-03)
                5. v0.5.0 (2025-01-03)
                6. v0.4.1 (2025-01-03)
                7. v0.4.0 (2025-01-03)
                8. v0.3.0 (2025-01-03)
                9. v0.2.0 (2025-01-03)
                10. v0.1.2 (2025-01-03)
                11. v0.1.1 (2025-01-03)
                12. v0.1.0 (2025-01-03)

              Related MCP Servers

              • -
                security
                A
                license
                -
                quality
                A Model Context Protocol (MCP) server that enables Claude or other LLMs to fetch content from URLs, supporting HTML, JSON, text, and images with configurable request parameters.
                Last updated -
                Python
                MIT License
              • -
                security
                A
                license
                -
                quality
                A Model Context Protocol server that integrates high-quality text-to-speech capabilities with Claude Desktop and other MCP-compatible clients, supporting multiple voice options and audio formats.
                Last updated -
                TypeScript
                MIT License
              • -
                security
                A
                license
                -
                quality
                An MCP server that enables LLMs to generate spoken audio from text using OpenAI's Text-to-Speech API, supporting various voices, models, and audio formats.
                Last updated -
                4
                1
                JavaScript
                MIT License
              • A
                security
                A
                license
                A
                quality
                An official Model Context Protocol (MCP) server that enables AI clients to interact with ElevenLabs' Text to Speech and audio processing APIs, allowing for speech generation, voice cloning, audio transcription, and other audio-related tasks.
                Last updated -
                19
                771
                Python
                MIT License
                • Apple

              View all related MCP servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/da-okazaki/mcp-fish-audio-server'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server