Fish Audio MCP Server

<div align="center"> <img src="./dcos/icon_fish-audio.webp" alt="Fish Audio Logo" width="300" height="300" /> </div>

这是一个 MCP（模型上下文协议）服务器，它提供了 Fish Audio 文字转语音 API 和像 Claude 这样的大型语言模型之间的无缝集成，实现了自然语言驱动的语音合成。

Fish Audio 是什么？

Fish Audio 是一个前沿的文字转语音平台，提供：

• 🌊 最先进的语音合成，具有自然的声音输出
• 🎯 语音克隆能力，用于创建自定义语音模型
• 🌍 多语言支持，包括英语、日语、中文等
• ⚡ 低延迟流式传输，适用于实时应用
• 🎨 精细控制，对语音韵律和情感进行控制

此 MCP 服务器将 Fish Audio 强大的功能直接带入您的大型语言模型工作流程中。

功能

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

快速开始

安装

您可以直接使用 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

3. 添加到您的 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_API_KEY	您的 Fish Audio API 密钥	-	是
FISH_MODEL_ID	使用的 TTS 模型（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	延迟模式（normal, balanced）	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

使用方法

一旦配置完成，Fish Audio MCP 服务器为大型语言模型提供了两个工具。

工具 1: fish_audio_tts

使用 Fish Audio 的 TTS 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（可选）：延迟模式（normal, balanced）
• output_path（可选）：自定义输出文件路径
• auto_play（可选）：自动播放生成的音频
• websocket_streaming（可选）：使用 WebSocket 流式传输而不是 HTTP
• realtime_play（可选）：在 WebSocket 流式传输期间实时播放音频

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

工具 2: fish_audio_list_references

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

参数

无需参数。

返回值

• 已配置语音参考的列表及其 ID、名称和标签
• 默认参考 ID

示例

基本文字转语音

用户："生成语音说 'Hello, world! Welcome to Fish Audio TTS.'"

Claude："我将使用 Fish Audio TTS 生成该文本的语音。"

[使用 fish_audio_tts 工具和 text 参数]

结果：音频文件保存至 ./audio_output/tts_2025-01-03T10-30-00.mp3

使用自定义语音 ID

用户："使用语音模型 xyz123 生成语音说 'This is a custom voice test'"

Claude："我将使用指定的语音模型生成语音。"

[使用 fish_audio_tts 工具和 text 和 reference_id 参数]

结果：使用自定义语音模型 xyz123 生成了语音

使用语音名称

用户："使用 Alice 的声音说 'Hello from Alice'"

Claude："我将使用 Alice 的声音生成语音。"

[使用 fish_audio_tts 工具和 reference_name: "Alice"]

结果：使用 Alice 的声音生成了语音

使用语音标签

用户："生成日语语音说 'こんにちは' 并使用动漫风格的声音"

Claude："我将使用动漫风格的声音生成日语语音。"

[使用 fish_audio_tts 工具和 reference_tag: "anime"]

结果：使用动漫风格的声音生成了语音

列出可用的语音

用户："有哪些可用的语音？"

Claude："我将列出所有已配置的语音参考。"

[使用 fish_audio_list_references 工具]

结果：
- Alice (id: id1) - 标签：female, english [默认]
- Bob (id: id2) - 标签：male, japanese
- Carol (id: id3) - 标签：female, japanese, anime

HTTP 流式传输模式

用户："在流式传输模式下生成关于人工智能优势的长篇语音"

Claude："我将在流式传输模式下生成语音，以便更快响应。"

[使用 fish_audio_tts 工具和 streaming: true]

结果：流式传输音频保存至 ./audio_output/tts_2025-01-03T10-35-00.mp3

WebSocket 实时流式传输

用户："实时流式传输并播放：'欢迎来到人工智能的未来'"

Claude："我将通过 WebSocket 流式传输并实时播放语音。"

[使用 fish_audio_tts 工具和 websocket_streaming: true, realtime_play: true]

结果：通过 WebSocket 实时流式传输并播放了音频

开发

本地开发

1. 克隆仓库：

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

2. 安装依赖：

npm install

3. 创建 .env 文件：

cp .env.example .env
# 编辑 .env 文件中的 API 密钥

4. 构建项目：

npm run build

5. 在开发模式下运行：

npm run dev

测试

运行测试套件：

npm test

项目结构

mcp-fish-audio-server/
├── src/
│   ├── index.ts          # MCP 服务器入口点
│   ├── tools/
│   │   └── tts.ts        # TTS 工具实现
│   ├── services/
│   │   └── fishAudio.ts  # Fish Audio API 客户端
│   ├── types/
│   │   └── index.ts      # TypeScript 定义
│   └── utils/
│       └── config.ts     # 配置管理
├── tests/                # 测试文件
├── audio_output/         # 默认音频输出目录
├── package.json
├── tsconfig.json
└── README.md

API 文档

Fish Audio 服务

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

1. generateSpeech：标准 TTS 生成

   • 返回音频缓冲区
   • 适合短文本
   • 内存占用较低

2. generateSpeechStream：流式 TTS 生成

   • 返回音频流
   • 适合长文本
   • 实时处理

错误处理

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

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

故障排除

常见问题

1. "FISH_API_KEY 环境变量是必需的"

   • 确保您设置了 FISH_API_KEY 环境变量
   • 检查 API 密钥是否有效

2. "网络错误：无法访问 Fish Audio API"

   • 检查您的互联网连接
   • 确认 Fish Audio API 可访问
   • 检查代理/防火墙问题

3. "文本长度超过最大限制"

   • 将长文本拆分为更小的部分
   • 最大支持长度为 10,000 字符

4. 音频文件未出现

   • 检查 AUDIO_OUTPUT_DIR 路径是否存在
   • 确认目录有写权限

贡献

欢迎贡献！请随意提交拉取请求。

1. 分叉仓库
2. 创建您的功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开拉取请求

许可证

本项目采用 MIT 许可证 - 详情参见 LICENSE 文件。

致谢

• Fish Audio 提供了优秀的 TTS API
• Anthropic 创建了模型上下文协议
• MCP 社区提供了灵感和示例

支持

对于问题、疑问或贡献，请访问 GitHub 仓库。

更新日志

详细变更列表，请参阅 CHANGELOG.md。