MCP Simple Aivisspeech

🚀 MCP Simple AivisSpeech

このプロジェクトは、AivisSpeechのテキスト読み上げエンジンとシームレスに統合するためのModel Context Protocol (MCP)サーバーです。AIアシスタントやアプリケーションが、カスタマイズ可能な音声パラメータでテキストを自然な日本語の音声に変換できるようになります。

English | 日本語

🙏 特別な感謝
このプロジェクトは@t09tanakaによるmcp-simple-voicevoxに基づいています。
彼らがVOICEVOX用のオリジナルのMCPサーバーを作成した素晴らしい仕事に深く感謝しています。これがこのAivisSpeechアダプテーションの基礎となりました。

🚀 クイックスタート

このセクションでは、MCP Simple AivisSpeechの基本的な使い方を説明します。まずは前提条件を満たし、サーバーの設定を行いましょう。

✨ 主な機能

• テキスト読み上げ変換 - AivisSpeechを使用した高品質の日本語音声合成
• 複数の音声キャラクター - 様々な話者と音声スタイルをサポート（デフォルト: Anneli ノーマル）
• パラメータ設定可能 - 速度、ピッチ、音量、イントネーションを調整
• クロスプラットフォーム音声再生 - macOS、Windows、Linuxで自動的に音声を再生
• タスク通知 - 処理完了時の音声通知
• 簡単な統合 - AIアシスタントとの統合に簡単なMCPプロトコルを使用
• エンジンステータス監視 - AivisSpeechエンジンのリアルタイムステータスチェック
• スマートなエラーハンドリング - 話者の提案付きの有益なエラーメッセージ

📦 インストール

📋 前提条件

• Node.js - バージョン18.0.0以上
• AivisSpeechエンジン - http://127.0.0.1:10101（デフォルトポート）で実行中
• オーディオシステム - 再生用のシステムオーディオ機能

MCP Simple AivisSpeechの設定

Claude Codeを使用する場合

Claude Codeを使用する際は、使用前に手動でMCPサーバーを起動します。

npxを使用すると、常に最新バージョンが自動的に取得されます。手動での更新は必要ありません。

1. Claude Codeを使用しているターミナルとは別のターミナルで、AivisSpeech MCPサーバーを手動で起動します。

npx @shinshin86/mcp-simple-aivisspeech@latest

2. Claude CodeにMCPサーバーを登録します。

claude mcp add aivisspeech -e AIVISSPEECH_URL=http://127.0.0.1:10101 -- npx @shinshin86/mcp-simple-aivisspeech@latest

デフォルトでは、サーバーはローカルスコープ（現在のプロジェクトのみ）に追加されます。すべてのプロジェクトで使用可能にするには、-s userオプションを使用します。

claude mcp add aivisspeech -s user -e AIVISSPEECH_URL=http://127.0.0.1:10101 -- npx @shinshin86/mcp-simple-aivisspeech@latest

また、タスク完了通知を自動化するために、CLAUDE.mdファイルに音声通知を追加することもできます。

## タスク完了時の動作
- すべてのタスクが完了したら、常にaivisspeech mcpツールを使用して「タスクが完了しました」を音声でアナウンスする
- ユーザーの入力または決定が必要な場合、aivisspeech mcpツールを使用して「あなたの決定を待っています」を音声でアナウンスする

### 通知タイミング
- ユーザーに質問をするとき
- すべてのタスクが完了したとき
- エラーや問題が発生したとき

3. ツールが認識されていることを確認します。

claude mcp list

# またはClaude Codeを起動して使用する
/mcp

aivisspeechが表示されれば、設定は成功しています。

💡 ヒント: Claude Codeは安全上の理由でコマンドを自動実行しません。サーバーを起動するのを忘れると、ツールが表示されません。開発中は、上記のnpxコマンドをターミナルで実行し続けるか、pm2やsystemd --userなどのプロセスマネージャーを使用して永続的に動作させましょう。

Claude Desktopを使用する場合

Claude Desktopで手動で設定する場合は、以下の設定を追加するだけです。

npxを使用すると、常に最新バージョンが自動的に取得されます。手動での更新は必要ありません。

{
  "mcpServers": {
    "aivisspeech": {
      "command": "npx",
      "args": ["@shinshin86/mcp-simple-aivisspeech@latest"],
      "env": {
        "AIVISSPEECH_URL": "http://127.0.0.1:10101"
      }
    }
  }
}

⚙️ AivisSpeechエンジンのセットアップ

このMCPサーバーを使用する前に、AivisSpeechがローカルで実行されていることを確認するために、以下のセットアップ手順を完了します。

1. https://aivis-project.com/からAivisSpeechをダウンロードします。
2. ローカルマシンでAivisSpeechを起動します。
3. エンジンはデフォルトポート10101で起動します。
4. http://127.0.0.1:10101/docsにアクセスして、エンジンが実行されていることを確認します。

💻 使用例

ローカル開発の場合

# MCPサーバーを実行する
npm start

# ホットリロードで開発する
npm run dev

# すべてが正常に動作していることを確認する
npm test

リポジトリをクローンし、依存関係をインストールし、ビルドするには：

# リポジトリをクローンする
git clone https://github.com/shinshin86/mcp-simple-aivisspeech.git
cd mcp-simple-aivisspeech

# 依存関係をインストールする
npm install

# プロジェクトをビルドする
npm run build

利用可能なツール

🎤 speak

テキストを音声に変換し、カスタマイズ可能な音声パラメータで音声を再生します。

このツールはいくつかの設定パラメータを受け入れます。以下のオプションが含まれます。

• text (必須): 音声に変換するテキスト
• speaker (オプション): 話者/音声ID（デフォルト: 888753760 - Anneli ノーマル）
• speedScale (オプション): 音声速度の倍率（0.5 - 2.0、デフォルト: 1.0）
• pitchScale (オプション): ピッチ調整（-0.15 - 0.15、デフォルト: 0.0）
• volumeScale (オプション): 音量レベル（0.0 - 2.0、デフォルト: 1.0）
• playAudio (オプション): 生成された音声を再生するかどうか（デフォルト: true）

使用例：

{
  "text": "こんにちは、世界！",
  "speaker": 888753760,
  "speedScale": 1.2,
  "pitchScale": 0.05,
  "volumeScale": 1.5
}

👥 get_speakers

利用可能なすべての音声キャラクターとそのスタイルのリストを取得します。

この関数は、ID、名前、および利用可能な音声スタイルを持つ話者のリストを返します。

🔔 notify_completion

タスクが完了したときに音声通知を再生します。

このツールはいくつかの設定パラメータを受け入れます。以下のオプションが含まれます。

• message (オプション): アナウンスする完了メッセージ（デフォルト: "処理が完了しました"）
• speaker (オプション): 通知音声の話者ID（デフォルト: 888753760 - Anneli ノーマル）

使用例：

{
  "message": "データ処理が完了しました",
  "speaker": 888753760
}

📊 check_engine_status

AivisSpeechエンジンの現在のステータスとバージョンを確認します。

この関数は、エンジンのステータス、バージョン情報、および接続詳細を返します。

📚 ドキュメント

🖥️ プラットフォームサポート

音声再生システム

テスト済み環境

• macOS 12+（Intel & Apple Silicon）
• Windows 10/11
• Ubuntu 20.04+
• Node.js 18.x、20.x、21.x

🧪 開発

利用可能なスクリプト

# 開発とビルド
npm run dev          # ホットリロードで実行する（tsx）
npm run build        # TypeScriptをdist/にコンパイルする
npm start           # コンパイルされたサーバーを実行する

# コード品質
npm run lint        # ESLintを実行する
npm run test        # Vitestテストを実行する（単一実行）
npm run test:watch  # ウォッチモードでテストを実行する
npm run test:ui     # UIでテストを実行する
npm run test:coverage # カバレッジを含めてテストを実行する

# ユーティリティ
npm run clean       # dist/ディレクトリをクリーンアップする

本番環境と開発環境での使用方法

本番環境でMCPクライアントを使用する場合は、MCP設定でnpx @shinshin86/mcp-simple-aivisspeech@latestを使用します。ローカル設定は必要なく、常に最新バージョンが取得されます。

開発用には、リポジトリをクローンし、ホットリロードで開発するにはnpm run devを使用し、本番ビルドをテストするにはnpm run build && npm startを使用します。

プロジェクトアーキテクチャ

mcp-simple-aivisspeech/
├── src/
│   ├── index.ts                  # MCPサーバーとツールハンドラー
│   └── aivisspeech-client.ts     # AivisSpeech APIクライアント
├── tests/
│   └── aivisspeech-client.test.ts # 単体テスト
├── dist/                         # コンパイルされた出力
├── docs/                         # ドキュメント
└── config files                  # TS、ESLint、Vitestの設定ファイル

APIクライアントアーキテクチャ

AivisSpeechClientクラスは包括的な機能を提供し、いくつかの重要な機能を備えています。

• HTTPクライアント - AxiosベースのAPI通信
• エラーハンドリング - 包括的なエラー捕捉と報告
• 型安全性 - すべてのAPIレスポンスに完全なTypeScriptインターフェースを提供
• 接続管理 - ヘルスチェックとステータス監視

新機能の追加方法

1. 新しいツール - src/index.tsのCallToolRequestSchemaにハンドラーを追加します。
2. APIメソッド - AivisSpeechClientクラスを拡張します。
3. 型 - aivisspeech-client.tsのインターフェースを更新します。
4. テスト - 対応するテストケースを追加します。

🔧 技術詳細

トラブルシューティング

一般的な問題

AivisSpeechエンジンが見つからない

Error: Failed to get version: connect ECONNREFUSED 127.0.0.1:10101

この問題を解決するには、AivisSpeechエンジンが正しいポートで実行されていることを確認します。

音声再生が失敗する

Error: Audio player exited with code 1

この問題を解決するには、以下のトラブルシューティングアプローチを検討してください。

• macOS - afplayが利用可能かどうかを確認する
• Linux - ALSAユーティリティをインストールする（sudo apt install alsa-utils）
• Windows - PowerShellの実行ポリシーがスクリプトを許可していることを確認する

アクセス許可が拒否される

Error: spawn afplay EACCES

この問題を解決するには、ファイルのアクセス許可とシステムのオーディオ設定を確認します。

デバッグモード

詳細なログを有効にするには、以下のコマンドを実行します。

DEBUG=mcp-aivisspeech npm run dev

📄 ライセンス

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

🤝 コントリビュート

コミュニティからのコントリビューションを歓迎します。コントリビューターは、以下の必須の手順を完了することで始めることができます。

1. リポジトリをフォークする
2. 機能ブランチを作成する（git checkout -b feature/amazing-feature）
3. 変更をコミットする（git commit -m 'Add amazing feature'）
4. ブランチにプッシュする（git push origin feature/amazing-feature）
5. プルリクエストを作成する

開発ガイドライン

• 既存のTypeScript/ESLint設定に従う
• 新しい機能に対してテストを追加する
• APIの変更に対してドキュメントを更新する
• クロスプラットフォーム互換性を確保する

🙏 謝辞

• AivisSpeech Projectの素晴らしいテキスト読み上げエンジン
• Model Context Protocolの統合フレームワーク
• VOICEVOX MCPのインスピレーションと参考

📞 サポート

• 問題 - GitHub Issues
• 議論 - GitHub Discussions
• ドキュメント - AivisSpeech API Docs

Made with ❤️ for the Japanese TTS community