shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

mcp-fish-audio-server

Fish Audio MCP服务器是一个提供文本转语音服务的中间件，通过Model Context Protocol实现与Claude等LLM的无缝集成，支持多语言、多音色和实时流式音频生成。

article

README

🚀 Fish Audio MCP 服务器

Fish Audio MCP 服务器是一个 MCP（模型上下文协议）服务器，它能让 Fish Audio 的文本转语音 API 与 Claude 等大语言模型（LLMs）实现无缝集成，从而实现由自然语言驱动的语音合成。

🚀 快速开始

安装

你可以直接使用 npx 运行这个 MCP 服务器：

npx @alanse/fish-audio-mcp-server

或者全局安装它：

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

配置

  1. 从 Fish Audio 获取你的 Fish Audio API 密钥。
  2. 设置环境变量：
export FISH_API_KEY=your_fish_audio_api_key_here
  1. 添加到你的 MCP 设置配置中：

单语音模式（简单模式）

{
  "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"
      }
    }
  }
}

多语音模式（高级模式）

{
  "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"
      }
    }
  }
}

✨ 主要特性

  • 🎙️ 高质量文本转语音：利用 Fish Audio 先进的文本转语音模型。
  • 🌊 流式支持：为低延迟应用提供实时音频流。
  • 🎨 多种语音：通过参考 ID 支持自定义语音模型。
  • 🎯 智能语音选择：可通过 ID、名称或标签选择语音。
  • 📚 语音库管理：配置和管理多个语音参考。
  • 🔧 灵活配置：基于环境变量进行配置。
  • 📦 多种音频格式：支持 MP3、WAV、PCM 和 Opus 格式。
  • 🚀 易于集成：可与任何 MCP 兼容的客户端轻松设置集成。

📦 安装指南

直接运行

npx @alanse/fish-audio-mcp-server

全局安装

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

💻 使用示例

基础用法

基本文本转语音

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

高级用法

使用自定义语音 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

使用语音名称

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

使用语音标签

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

列出可用语音

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 流式模式

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 实时流式传输

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

📚 详细文档

环境变量

| 属性 | 详情 | 默认值 | 是否必需 | |------|------|--------|----------| | FISH_API_KEY | 你的 Fish Audio API 密钥 | - | 是 | | FISH_MODEL_ID | 要使用的文本转语音模型（s1、speech-1.5、speech-1.6） | s1 | 可选 | | FISH_REFERENCE_ID | 默认语音参考 ID（单参考模式） | - | 可选 | | FISH_REFERENCES | 多个语音参考（见下文） | - | 可选 | | FISH_DEFAULT_REFERENCE | 使用多个参考时的默认参考 ID | - | 可选 | | FISH_OUTPUT_FORMAT | 默认音频格式（mp3、wav、pcm、opus） | mp3 | 可选 | | FISH_STREAMING | 启用流式模式（HTTP/WebSocket） | false | 可选 | | FISH_LATENCY | 延迟模式（正常、平衡） | balanced | 可选 | | FISH_MP3_BITRATE | MP3 比特率（64、128、192） | 128 | 可选 | | FISH_AUTO_PLAY | 自动播放音频并启用实时播放 | false | 可选 | | AUDIO_OUTPUT_DIR | 音频文件输出目录 | ~/.fish-audio-mcp/audio_output | 可选 |

配置多个语音参考

JSON 数组格式（推荐）

使用 FISH_REFERENCES 环境变量和 JSON 数组：

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_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

工具使用

工具 1: fish_audio_tts

使用 Fish Audio 的文本转语音 API 从文本生成语音。

参数
  • text（必需）：要转换为语音的文本（最多 10,000 个字符）
  • reference_id（可选）：语音模型参考 ID
  • reference_name（可选）：按名称选择语音
  • reference_tag（可选）：按标签选择语音
  • streaming（可选）：启用流式模式
  • format（可选）：输出格式（mp3、wav、pcm、opus）
  • mp3_bitrate（可选）：MP3 比特率（64、128、192）
  • normalize（可选）：启用文本规范化（默认：true）
  • latency（可选）：延迟模式（正常、平衡）
  • output_path（可选）：自定义输出文件路径
  • auto_play（可选）：自动播放生成的音频
  • websocket_streaming（可选）：使用 WebSocket 流式传输而不是 HTTP
  • realtime_play（可选）：在 WebSocket 流式传输期间实时播放音频

语音选择优先级：reference_id > reference_name > reference_tag > 默认

工具 2: fish_audio_list_references

列出所有配置的语音参考。

参数

无需参数。

返回值
  • 列出所有配置的语音参考及其 ID、名称和标签
  • 默认参考 ID

🔧 技术细节

本地开发

  1. 克隆仓库：
git clone https://github.com/da-okazaki/mcp-fish-audio-server.git
cd mcp-fish-audio-server
  1. 安装依赖：
npm install
  1. 创建 .env 文件：
cp .env.example .env
# Edit .env with your API key
  1. 构建项目：
npm run build
  1. 在开发模式下运行：
npm run dev

测试

运行测试套件：

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

📄 许可证

本项目采用 MIT 许可证，请参阅 LICENSE 文件获取详细信息。

API 文档

Fish Audio 服务

该服务提供两个主要方法：

  1. generateSpeech：标准文本转语音生成
    • 返回音频缓冲区
    • 适用于短文本
    • 内存使用较低
  2. generateSpeechStream：流式文本转语音生成
    • 返回音频流
    • 适用于长文本
    • 实时处理

错误处理

服务器处理各种错误场景：

  • INVALID_API_KEY：API 密钥无效或缺失
  • NETWORK_ERROR：与 Fish Audio API 的连接问题
  • INVALID_PARAMS：请求参数无效
  • QUOTA_EXCEEDED：API 速率限制超出
  • SERVER_ERROR：Fish Audio 服务器错误

故障排除

常见问题

  1. "FISH_API_KEY environment variable is required"
    • 确保你已设置 FISH_API_KEY 环境变量
    • 检查 API 密钥是否有效
  2. "Network error: Unable to reach Fish Audio API"
    • 检查你的互联网连接
    • 验证 Fish Audio API 是否可访问
    • 检查代理/防火墙问题
  3. "Text length exceeds maximum limit"
    • 拆分长文本
    • 最大支持长度为 10,000 个字符
  4. Audio files not appearing
    • 检查 AUDIO_OUTPUT_DIR 路径是否存在
    • 确保该目录有写入权限
help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端