How do I use MCP FishAudio Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP FishAudio Server convert this text to speech using the Alice voice" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP FishAudio Server

by da-okazaki

Overview Schema Related Servers Score Discussions

TypeScript

Remote

Fish Audio MCP Server

npm version License: MIT

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.

Related MCP server: TTS-MCP

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:

npx @alanse/fish-audio-mcp-server

Or install it globally:

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

Configuration

Get your Fish Audio API key from Fish Audio
Set up environment variables:

export FISH_API_KEY=your_fish_audio_api_key_here

Add to your MCP settings configuration:

Single Voice Mode (Simple)

{
  "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": "speech-1.6",
        "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"
      }
    }
  }
}

Multiple Voice Mode (Advanced)

{
  "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": "speech-1.6",
        "FISH_REFERENCES": "[{'reference_id':'id1','name':'Alice','tags':['female','english']},{'reference_id':'id2','name':'Bob','tags':['male','japanese']},{'reference_id':'id3','name':'Carol','tags':['female','japanese','anime']}]",
        "FISH_DEFAULT_REFERENCE": "id1",
        "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

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 (single reference mode)	-	Optional
`FISH_REFERENCES`	Multiple voice references (see below)	-	Optional
`FISH_DEFAULT_REFERENCE`	Default reference ID when using multiple references	-	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

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:

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

Individual Format (Backward Compatibility)

Use numbered environment variables:

FISH_REFERENCE_1_ID=id1
FISH_REFERENCE_1_NAME=Alice
FISH_REFERENCE_1_TAGS=female,english

FISH_REFERENCE_2_ID=id2
FISH_REFERENCE_2_NAME=Bob
FISH_REFERENCE_2_TAGS=male,japanese

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

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 by ID

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

Using Voice by Name

User: "Use Alice's voice to say 'Hello from Alice'"

Claude: I'll generate speech using Alice's voice.

[Uses fish_audio_tts tool with reference_name: "Alice"]

Result: Audio generated with Alice's voice

Using Voice by Tag

User: "Generate Japanese speech saying 'こんにちは' with an anime voice"

Claude: I'll generate Japanese speech with an anime-style voice.

[Uses fish_audio_tts tool with reference_tag: "anime"]

Result: Audio generated with anime voice style

List Available Voices

User: "What voices are available?"

Claude: I'll list all configured voice references.

[Uses fish_audio_list_references tool]

Result:
- Alice (id: id1) - Tags: female, english [Default]
- Bob (id: id2) - Tags: male, japanese
- Carol (id: id3) - Tags: female, japanese, anime

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

Clone the repository:

git clone https://github.com/da-okazaki/mcp-fish-audio-server.git
cd mcp-fish-audio-server

Install dependencies:

npm install

Create .env file:

cp .env.example .env
# Edit .env with your API key

Build the project:

npm run build

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:

generateSpeech: Standard TTS generation
- Returns audio buffer
- Suitable for short texts
- Lower memory usage
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

"FISH_API_KEY environment variable is required"
- Ensure you've set the FISH_API_KEY environment variable
- Check that the API key is valid
"Network error: Unable to reach Fish Audio API"
- Check your internet connection
- Verify Fish Audio API is accessible
- Check for proxy/firewall issues
"Text length exceeds maximum limit"
- Split long texts into smaller chunks
- Maximum supported length is 10,000 characters
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.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
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.

Available Tools

2 tools

fish_audio_list_referencesB

List all configured voice references

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it's a list operation, implying it's likely read-only and non-destructive, but doesn't confirm this or add details like pagination, rate limits, or authentication needs. The description is minimal and lacks rich behavioral context beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose with no wasted words. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 0 parameters, no annotations, and no output schema, the description is minimal but covers the basic purpose. However, for a tool with no structured data support, it lacks details on return values, error handling, or behavioral traits, making it adequate but with clear gaps in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and schema description coverage is 100%, so there are no parameters to document. The description doesn't need to add parameter semantics, and it appropriately doesn't mention any. A baseline of 4 is applied as it handles the zero-parameter case adequately without unnecessary information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List') and the resource ('all configured voice references'), providing a specific verb+resource combination. However, it doesn't differentiate from its sibling tool 'fish_audio_tts', which appears to be a text-to-speech tool rather than a listing tool, so the distinction is inherent but not explicitly stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention the sibling tool 'fish_audio_tts' or any other context for usage, leaving the agent without explicit when/when-not instructions or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fish_audio_ttsC

Generate speech from text using Fish Audio TTS API

ParametersJSON Schema

Name	Required	Description	Default
`auto_play`	No	Automatically play the generated audio (optional)
`format`	No	Output audio format (optional)	mp3
`latency`	No	Latency mode (optional)	balanced
`mp3_bitrate`	No	MP3 bitrate in kbps (optional)
`normalize`	No	Enable text normalization (optional)
`output_path`	No	Custom output file path (optional)
`realtime_play`	No	Enable real-time audio playback during streaming (optional)
`reference_id`	No	Voice model reference ID (optional)
`reference_name`	No	Voice model name to search for (optional)
`reference_tag`	No	Voice model tag to search for (optional)
`streaming`	No	Enable HTTP streaming mode (optional)
`text`	Yes	Text to convert to speech
`websocket_streaming`	No	Enable WebSocket streaming mode (optional)

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool generates speech but doesn't cover critical aspects like rate limits, authentication requirements, error handling, or what the output looks like (e.g., audio file, URL, or stream). For a TTS tool with 13 parameters and no output schema, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, with zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (13 parameters, no annotations, no output schema), the description is incomplete. It doesn't explain the return value (e.g., audio data or file path), error conditions, or behavioral traits like streaming implications. For a TTS tool with many optional parameters, more context is needed to guide effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 13 parameters. The description adds no additional parameter information beyond what's in the schema. According to the rules, when coverage is high (>80%), the baseline score is 3 even with no param info in the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Generate speech from text using Fish Audio TTS API.' It specifies the verb ('Generate speech') and resource ('from text'), but doesn't differentiate from its sibling tool 'fish_audio_list_references', which appears to serve a different function (listing references rather than generating speech).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention the sibling tool or any other TTS options, nor does it specify prerequisites or contexts for use. The agent must infer usage from the tool name and parameters alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

2 tool updatesv1.0.0Sep 20, 2025
- First observedfish_audio_list_references
- First observedfish_audio_tts

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.1/5.0

Disambiguation5/5

The two tools have clearly distinct purposes: one lists voice references (a read-only operation), and the other generates speech (a synthesis operation). There is no overlap or ambiguity between these functions, making it easy for an agent to select the correct tool.

Naming Consistency5/5

Both tools follow a consistent snake_case naming pattern with a 'fish_audio_' prefix, followed by a descriptive verb_noun combination (list_references and tts). This uniformity enhances readability and predictability across the tool set.

Tool Count2/5

With only two tools, the server feels under-scoped for a TTS API domain. Key operations like managing references (e.g., create, update, delete) or configuring TTS parameters are missing, limiting the server's utility and forcing agents to work around gaps.

Completeness2/5

The tool set is severely incomplete for a TTS API. While it covers listing references and generating speech, it lacks essential CRUD operations for references (e.g., create, update, delete) and configuration tools (e.g., set parameters, list voices). This will likely cause agent failures in common workflows.

Maintenance

ActivityInactive

ResponsivenessUnresponsive

Resources

Need Help?

Reddit Discussion

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

mcp-fish
io.github.AceDataCloud
MCP server exposing the AceDataCloud Fish Audio API (text-to-speech with voice conditioning)
Text-to-Speech Speech Processing
21
Texttospeech Mcp C
io.github.varvararatta
MCP server for Text-to-Speech
Text-to-Speech Speech Processing Audio Processing
2
hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
237
Artificial Wit AI
com.artificialwit
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
ERP Systems CRM Knowledge & Memory
2

Related MCP Servers

MCP Server Example
Developer Tools Code Execution Autonomous Agents
alejandro-ao
A
license
B
quality
D
maintenance
An educational implementation of a Model Context Protocol server that demonstrates how to build a functional MCP server for integrating with various LLM clients like Claude Desktop.
Updated a year ago (2025-04-29 10:58 UTC)
1
163
MIT
TTS-MCP
Text-to-Speech Audio Processing
nakamurau1
A
license
Not graded
quality
C
maintenance
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.
Updated a year ago (2025-03-25 14:34 UTC)
17
1
MIT
Blabber-MCP
Text-to-Speech Speech Processing App Automation
pinkpixel-dev
A
license
A
quality
D
maintenance
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.
Updated 3 months ago (2026-06-21 02:16 UTC)
1
13
1
MIT
Rime MCP
Text-to-Speech Speech Processing Code Execution
MatthewDailey
A
license
A
quality
D
maintenance
A Model Context Protocol server that enables AI models to generate and play high-quality text-to-speech audio through your device's native audio system using Rime's voice synthesis API.
Updated a year ago (2025-05-29 22:16 UTC)
1
81
27
-

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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

Fish Audio MCP Server

What is Fish Audio?

Features

Quick Start

Installation

Configuration

Single Voice Mode (Simple)

Multiple Voice Mode (Advanced)

Environment Variables

Configuring Multiple Voice References

JSON Array Format (Recommended)

Individual Format (Backward Compatibility)

Usage

Tool 1: fish_audio_tts

Parameters

Tool 2: fish_audio_list_references

Parameters

Returns

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

Testing

Project Structure

API Documentation

Fish Audio Service

Error Handling

Troubleshooting

Common Issues

Contributing

License

Acknowledgments

Support

Changelog

Available Tools

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

MCP Server Example

TTS-MCP

Blabber-MCP

Rime MCP

Latest Blog Posts

MCP directory API

Tool 1: `fish_audio_tts`

Tool 2: `fish_audio_list_references`