Fish Audio MCP Server Integrating Claude for Text-to-Speech

Overview

This MCP (Model Context Protocol) server connects Fish Audio’s text-to-speech (TTS) capabilities with LLMs such as Claude. Running the server alongside your LLM lets the model request high-quality speech synthesis directly from natural-language prompts. The server translates MCP tool calls into Fish Audio API requests, returning generated audio files or streaming audio for low-latency use cases.

Use this server when you want to add premium, multilingual voice output to chatbot agents, voice assistants, demos, or accessibility features. It supports single-voice and multi-voice setups, streaming or batch synthesis, and common audio formats (MP3, WAV, PCM, Opus).

Repository: https://github.com/da-okazaki/mcp-fish-audio-server

Features

• High-fidelity TTS via Fish Audio models
• Low-latency streaming (HTTP/WebSocket) for real-time playback
• Support for reference voice models (voice cloning / custom voices)
• Select voices by ID, name, or tags
• Multiple audio formats: mp3, wav, pcm, opus
• Configurable MP3 bitrate and latency mode
• Simple environment-variable configuration for MCP deployments
• Outputs audio files to disk and can auto-play locally for debugging

Installation / Configuration

Install and run with npx (no global install required):

npx @alanse/fish-audio-mcp-server

Or install globally:

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

Basic environment setup (single voice):

export FISH_API_KEY="your_fish_audio_api_key"
export FISH_MODEL_ID="speech-1.6"
export FISH_REFERENCE_ID="your_voice_reference_id"
export FISH_OUTPUT_FORMAT="mp3"
export AUDIO_OUTPUT_DIR="$HOME/.fish-audio-mcp/audio_output"

Example MCP server entry (for an MCP-enabled LLM such as Claude via an MCP manager):

{
  "mcpServers": {
    "fish-audio": {
      "command": "npx",
      "args": ["-y", "@alanse/fish-audio-mcp-server"],
      "env": {
        "FISH_API_KEY": "your_fish_audio_api_key",
        "FISH_MODEL_ID": "speech-1.6",
        "FISH_REFERENCE_ID": "your_voice_reference_id",
        "FISH_OUTPUT_FORMAT": "mp3",
        "AUDIO_OUTPUT_DIR": "~/.fish-audio-mcp/audio_output"
      }
    }
  }
}

Environment Variables

Configuring Multiple Voice References

Recommended: set FISH_REFERENCES as a JSON array:

export FISH_REFERENCES='[
  {"reference_id":"id1","name":"Alice","tags":["female","english"]},
  {"reference_id":"id2","name":"Bob","tags":["male","japanese"]}
]'
export FISH_DEFAULT_REFERENCE="id1"

Backward-compatible option: number individual environment variables:

export FISH_REFERENCE_1_ID="id1"
export FISH_REFERENCE_1_NAME="Alice"
export FISH_REFERENCE_1_TAGS="female,english"

Available Tools / Resources

The MCP server exposes tools that LLMs can call.

• fish_audio_tts

  • Converts text to speech using Fish Audio.
  • Input parameters:
    • text (string, required, up to ~10,000 chars)
    • reference_id (string, optional) — voice reference ID
    • reference_name (string, optional) — match voice by name
    • reference_tag (string, optional) — match voice by tag
    • streaming (bool, optional) — request streaming output
    • format (string, optional) — mp3, wav, pcm, opus
    • mp3_bitrate (number, optional) — 64, 128, or 192
    • normalize (bool, optional) — normalize audio loudness
  • Output:
    • Non-streaming: path to generated audio file (AUDIO_OUTPUT_DIR)
    • Streaming: streaming URL or chunked audio via MCP streaming channel

• fish_audio_list_references

  • Returns configured voice references (IDs, names, tags) so the LLM can choose voices programmatically.

Use Cases

• Voice-enabled chatbots: Have Claude generate textual responses and call fish_audio_tts to return spoken output in a selected voice.
  • Example: User asks for a Japanese explanation; the model calls fish_audio_tts with reference_tag=“japanese” and format=“mp3”.
• Dynamic multi-voice narration: Select different reference_ids to create multi-character narration for audiobooks or interactive fiction.
• Real-time assistants: Enable FISH_STREAMING=true and FISH_AUTO_PLAY to stream responses with minimal latency for live agents or demos.
• Accessibility: Convert long-form instructions into spoken audio files stored in AUDIO_OUTPUT_DIR for offline use.

Example tool call (JSON representation)

Non-streaming synthesis:

{
  "tool": "fish_audio_tts",
  "input": {
    "text": "Hello! This response will be converted to high-quality speech.",
    "reference_tag": "female",
    "format": "mp3",
    "mp3_bitrate": 128
  }
}

Expected result: the MCP server returns a path like /home/user/.fish-audio-mcp/audio_output/tts-2026-04-09-1234.mp3

Streaming synthesis:

{
  "tool": "fish_audio_tts",
  "input": {
    "text": "This will be streamed in near real-time.",
    "streaming": true,
    "format": "opus"
  }
}

The server will provide a streaming endpoint or stream audio chunks through the MCP client.

Notes and best practices

• Keep your FISH_API_KEY secret and scope it appropriately.
• For production low-latency use, enable streaming and tune FISH_LATENCY.
• Use FISH_REFERENCES to centralize voice management and let the model choose