MCP Fish Audio Server

🚀 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

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

📚 詳細文檔

環境變量

配置多個語音參考

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

2. 安裝依賴：

npm install

3. 創建 .env 文件：

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

4. 構建項目：

npm run build

5. 在開發模式下運行：

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 路徑是否存在
   • 確保該目錄有寫入權限