MCP Fish Audio Server

🚀 Fish Audio MCP Server

Fish Audio MCP Serverは、Fish Audioのテキスト読み上げAPIとClaudeなどの大規模言語モデル（LLM）をシームレスに統合するMCP（Model Context Protocol）サーバーです。自然言語による音声合成を可能にします。

🚀 クイックスタート

インストール

このMCPサーバーは、npxを使って直接実行することができます。

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互換クライアントと簡単にセットアップできます。

📦 インストール

上述のクイックスタートセクションを参照してください。

💻 使用例

基本的な使用法

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

📚 ドキュメント

環境変数

複数のボイス参照の構成

複数のボイス参照を2つの方法で構成できます。

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に2つのツールを提供します。

ツール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（オプション）: 遅延モード (normal, balanced)
• output_path（オプション）: カスタム出力ファイルパス
• auto_play（オプション）: 生成されたオーディオを自動再生する
• websocket_streaming（オプション）: HTTPの代わりにWebSocketストリーミングを使用する
• 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
# あなたのAPIキーで.envを編集します

4. プロジェクトをビルドします。

npm run build

5. 開発モードで実行します。

npm run dev

テスト

テストスイートを実行します。

npm test

プロジェクト構造

mcp-fish-audio-server/
├── src/
│   ├── index.ts          # MCPサーバーのエントリポイント
│   ├── tools/
│   │   └── tts.ts        # テキスト読み上げツールの実装
│   ├── 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サービス

このサービスは2つの主要なメソッドを提供します。

1. generateSpeech: 標準のテキスト読み上げ生成
   • オーディオバッファを返します。
   • 短いテキストに適しています。
   • 低メモリ使用量です。
2. generateSpeechStream: ストリーミングテキスト読み上げ生成
   • オーディオストリームを返します。
   • 長いテキストに適しています。
   • リアルタイム処理が可能です。

エラー処理

サーバーはさまざまなエラーシナリオを処理します。

• INVALID_API_KEY: 無効または欠落しているAPIキー
• NETWORK_ERROR: Fish Audio APIとの接続問題
• INVALID_PARAMS: 無効なリクエストパラメータ
• QUOTA_EXCEEDED: APIレート制限を超えた
• SERVER_ERROR: Fish Audioサーバーエラー

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細についてはLICENSEファイルを参照してください。

トラブルシューティング

一般的な問題

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パスが存在することを確認してください。
   • ディレクトリに書き込み権限があることを確認してください。

貢献

貢献は大歓迎です！プルリクエストを送信してください。

1. リポジトリをフォークします。
2. あなたの機能ブランチを作成します (git checkout -b feature/AmazingFeature)。
3. 変更をコミットします (git commit -m 'Add some AmazingFeature')。
4. ブランチにプッシュします (git push origin feature/AmazingFeature)。
5. プルリクエストを開きます。

謝辞

• Fish Audioには優れたテキスト読み上げAPIを提供してくれたことに感謝します。
• AnthropicにはModel Context Protocolを作成してくれたことに感謝します。
• MCPコミュニティにはインスピレーションと例を提供してくれたことに感謝します。

サポート

問題、質問、または貢献については、GitHubリポジトリを訪問してください。

変更履歴

詳細な変更履歴についてはCHANGELOG.mdを参照してください。