MCP Simple Aivisspeech

🚀 MCP Simple AivisSpeech

MCP Simple AivisSpeech 是一个基于模型上下文协议（MCP）的服务器，可与 AivisSpeech 文本转语音引擎无缝集成。该项目能让 AI 助手和应用程序将文本转换为自然流畅的日语语音，并可自定义语音参数。

🚀 快速开始

前提条件

• 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 验证引擎是否正在运行

✨ 主要特性

• 文本转语音转换 - 使用 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

💻 使用示例

基础用法

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

高级用法

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

📚 详细文档

可用工具

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

👥 get_speakers

检索所有可用的语音角色及其风格列表。

此函数返回：包含说话者 ID、名称和可用语音风格的列表。

🔔 notify_completion

任务完成时播放语音通知。

此工具接受多个配置参数，包括以下选项：

• message (可选)：要宣布的完成消息（默认："処理が完了しました"）
• speaker (可选)：通知语音的说话者 ID（默认：888753760 - Anneli ノーマル）

📊 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 utils（sudo apt install alsa-utils）
• Windows - 确保 PowerShell 执行策略允许脚本运行

权限被拒绝

Error: spawn afplay EACCES

解决此问题可考虑以下故障排除方法：检查文件权限和系统音频设置。

调试模式

要启用详细日志记录，请运行以下命令：

DEBUG=mcp-aivisspeech npm run dev

📄 许可证

本项目采用 Apache 许可证 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 项目 提供了出色的 TTS 引擎
• 模型上下文协议 提供了集成框架
• VOICEVOX MCP 提供了灵感和参考

📞 支持

• 问题反馈 - GitHub Issues
• 讨论交流 - GitHub Discussions
• 文档查阅 - AivisSpeech API 文档

❤️ 为日语 TTS 社区精心打造