fish-audio-server readme

Fish音频MCP服务器

](https://badge.fury.io/js/@alanse%2Ffish-audio-mcp-server) 

一个MCP（模型上下文协议）服务器，提供Fish Audio的文本到速度API和Claude等LLM之间的无缝集成，实现自然语言驱动的语音合成。

什么是Fish Audio？

鱼音频 是一个尖端的文本转语音平台，提供：

• 🌊 最先进的语音合成技术 具有自然声音输出
• 🎯 语音克隆功能 创建自定义语音模型
• 🌍 多语言支持 包括英语、日语、中文等
• ⚡ 低延迟流媒体 用于实时应用程序
• 🎨 细粒度控制 言语韵律与情感

此MCP服务器将Fish Audio的强大功能直接带到您的LLM工作流程中。

特性

• 🎙️ 高品质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 API密钥 鱼音频

1. 设置环境变量：

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

环境变量

配置多个语音引用

您可以通过两种方式配置多个语音引用：

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服务器为LLM提供了两个工具。

工具1： fish_audio_tts

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

参数

• text （必填）：要转换为语音的文本（最多10000个字符）
• reference_id （可选）：语音模型参考ID
• reference_name （可选）：按名称选择语音
• reference_tag （可选）：按标签选择语音
• streaming （可选）：启用流媒体模式
• format （可选）：输出格式（mp3、wav、pcm、opus）
• mp3_bitrate （可选）：MP3比特率（64128192）
• 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

例子

基本文本转语音

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

发展

地方发展

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

API文档

鱼音频服务

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

1. 发电机语音：标准TTS生成

- 返回音频缓冲区 - 适用于短文本 - 降低内存使用率

1. generateSpeechStream 的：流式TTS生成

- 返回音频流 - 适用于长文本 - 实时处理

错误处理

服务器处理各种错误情况：

• 无效的API_KEY：API密钥无效或丢失
• 网络错误：Fish Audio API的连接问题
• INVALID_param：请求参数无效
• 超出配额：超过API费率限制
• 服务器错误：Fish Audio服务器错误

故障排除

常见问题

1. “FISH_API_KEY环境变量是必需的”

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

1. “网络错误：无法访问Fish Audio API”

- 检查您的互联网连接 - 验证Fish Audio API是否可访问 - 检查代理/防火墙问题

1. “文本长度超过最大限制”

- 将长文本分割成更小的块 - 支持的最大长度为10000个字符

1. 音频文件未出现

- 检查 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许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• 鱼音频 提供出色的TTS API
• Anthropic 用于创建模型上下文协议
• MCP社区的灵感和例子

支持

有关问题、疑问或贡献，请访问 .

更新日志

看 更改日志.md 查看详细的更改列表。