@alanse/fish-audio-mcp-server
Advanced tools
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.
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
Get your Fish Audio API key from Fish Audio
Set up environment variables:
export FISH_API_KEY=your_fish_audio_api_key_here
{
"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"
}
}
}
}
| Variable | Description | Default | Required |
|---|---|---|---|
FISH_API_KEY | Your Fish Audio API key | - | Yes |
FISH_MODEL_ID | TTS model to use (s1, speech-1.5, speech-1.6) | s1 | Optional |
FISH_REFERENCE_ID | Default voice reference ID | - | Optional |
FISH_OUTPUT_FORMAT | Default audio format (mp3, wav, pcm, opus) | mp3 | Optional |
FISH_STREAMING | Enable streaming mode (HTTP/WebSocket) | false | Optional |
FISH_LATENCY | Latency mode (normal, balanced) | balanced | Optional |
FISH_MP3_BITRATE | MP3 bitrate (64, 128, 192) | 128 | Optional |
FISH_AUTO_PLAY | Auto-play audio and enable real-time playback | false | Optional |
AUDIO_OUTPUT_DIR | Directory for audio file output | ~/.fish-audio-mcp/audio_output | Optional |
Once configured, the Fish Audio MCP server provides the fish_audio_tts tool to LLMs.
fish_audio_ttsGenerates speech from text using Fish Audio's TTS API.
text (required): Text to convert to speech (max 10,000 characters)reference_id (optional): Voice model reference IDstreaming (optional): Enable streaming modeformat (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 pathauto_play (optional): Automatically play the generated audiowebsocket_streaming (optional): Use WebSocket streaming instead of HTTPrealtime_play (optional): Play audio in real-time during WebSocket streamingUser: "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
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
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
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
git clone https://github.com/da-okazaki/mcp-fish-audio-server.git
cd mcp-fish-audio-server
npm install
.env file:cp .env.example .env
# Edit .env with your API key
npm run build
npm run dev
Run the test suite:
npm test
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
The service provides two main methods:
generateSpeech: Standard TTS generation
generateSpeechStream: Streaming TTS generation
The server handles various error scenarios:
"FISH_API_KEY environment variable is required"
FISH_API_KEY environment variable"Network error: Unable to reach Fish Audio API"
"Text length exceeds maximum limit"
Audio files not appearing
AUDIO_OUTPUT_DIR path existsContributions are welcome! Please feel free to submit a Pull Request.
git checkout -b feature/AmazingFeature)git commit -m 'Add some AmazingFeature')git push origin feature/AmazingFeature)This project is licensed under the MIT License - see the LICENSE file for details.
For issues, questions, or contributions, please visit the GitHub repository.
websocket_streaming and realtime_playauto_play parameterFAQs
MCP server for Fish Audio Text-to-Speech integration
The npm package @alanse/fish-audio-mcp-server receives a total of 31 weekly downloads. As such, @alanse/fish-audio-mcp-server popularity was classified as not popular.
We found that @alanse/fish-audio-mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh discusses the recent npm supply chain attacks on PodRocket, covering novel attack vectors and how developers can protect themselves.
Security News
Maintainers back GitHub’s npm security overhaul but raise concerns about CI/CD workflows, enterprise support, and token management.
Product
Socket Firewall is a free tool that blocks malicious packages at install time, giving developers proactive protection against rising supply chain attacks.