MCP Simple Aivisspeech

🚀 MCP Simple AivisSpeech

MCP Simple AivisSpeech 是一個基於模型上下文協議（MCP）的服務器，可與 AivisSpeech 文本轉語音引擎無縫集成。該項目能讓 AI 助手和應用程序將文本轉換為自然流暢的日語語音，還能自定義語音參數。

English | 日本語

🙏 特別感謝
本項目基於 @t09tanaka 的 mcp-simple-voicevox 開發。
我們非常感謝他們為 VOICEVOX 創建的優秀 MCP 服務器，這為 AivisSpeech 的適配奠定了基礎。

🚀 快速開始

在使用本項目前，請確保滿足以下先決條件：

• Node.js - 版本 18.0.0 或更高
• AivisSpeech 引擎 - 在 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 驗證引擎是否正在運行。

使用 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 進行高質量的日語語音合成。
• 多種語音角色 - 支持多種說話者和語音風格（默認：Anneli ノーマル）。
• 可配置參數 - 可調整語速、音高、音量和語調。
• 跨平臺音頻 - 可在 macOS、Windows 和 Linux 上自動播放音頻。
• 任務通知 - 任務完成時進行語音通知。
• 易於集成 - 提供簡單的 MCP 協議，便於 AI 助手集成。
• 引擎狀態監控 - 實時檢查 AivisSpeech 引擎的狀態。
• 智能錯誤處理 - 提供有用的錯誤消息和發音建議。

📦 安裝指南

本地開發

# 克隆倉庫
git clone https://github.com/shinshin86/mcp-simple-aivisspeech.git
cd mcp-simple-aivisspeech

# 安裝依賴
npm install

# 構建項目
npm run build

運行 MCP 服務器

# 運行 MCP 服務器
npm start

# 開發時熱重載
npm run dev

# 檢查是否一切正常
npm test

💻 使用示例

基礎用法

🎤 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/ 目錄

本地與 NPX 使用

在生產環境中使用 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. Fork 倉庫。
2. 創建 一個功能分支（git checkout -b feature/amazing-feature）。
3. 提交 您的更改（git commit -m 'Add amazing feature'）。
4. 推送 到分支（git push origin feature/amazing-feature）。
5. 打開 一個 Pull Request。

開發指南

• 遵循現有的 TypeScript/ESLint 配置。
• 為新功能添加測試。
• 更新 API 更改的文檔。
• 確保跨平臺兼容性。

🙏 致謝

• AivisSpeech 項目 提供了優秀的 TTS 引擎。
• 模型上下文協議 提供了集成框架。
• VOICEVOX MCP 提供了靈感和參考。

📞 支持

• 問題 - GitHub Issues
• 討論 - GitHub Discussions
• 文檔 - AivisSpeech API 文檔

為日語 TTS 社區用心打造 ❤️