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 社区用心打造 ❤️