MCP Simple AivisSpeech

MCP简易语音

Project Logo

英语 | 日本语

🙏 特别感谢\ 我们非常感谢他们为VOICEVOX创建原始MCP服务器的出色工作，这是AivisSpeech适配的基础。

用于与AivisSpeech文本到语音引擎无缝集成的模型上下文协议（MCP）服务器。该项目使人工智能助手和应用程序能够将文本转换为具有可定制语音参数的自然发音的日语语音。

✨ 特性

• 文本到语音转换-使用AivisSpeech进行高质量日语语音合成
• 多个语音字符-支持各种扬声器和语音风格（默认：Anneliノーマル)
• 可配置参数-调整速度、音高、音量和语调
• 跨平台音频-在macOS、Windows和Linux上自动播放音频
• 任务通知-流程完成的语音通知
• 易于集成-用于AI助手集成的简单MCP协议
• 发动机状态监测-AivisSpeech发动机的实时状态检查
• 智能错误处理-有用的错误消息和演讲者建议

📋 先决条件

• Node.js-18.0.0或更高版本
• AivisSpeech引擎-正在运行 http://127.0.0.1:10101 （默认端口）
• 音响系统-用于播放的系统音频功能

MCP简单AivisSpeech配置

使用克劳德代码

使用Claude Code时，在使用之前手动启动MCP服务器。

使用npx可确保您始终自动获得最新版本。无需手动更新。

1. 在与使用Claude Code的终端不同的单独终端中手动启动AivisSpeech MCP服务器

npx @shinshin86/mcp-simple-aivisspeech@latest

1. 使用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文件中，以自动化任务完成通知：

## Task Completion Behavior
- When all tasks are completed, always use the aivisspeech mcp tool to announce "Tasks completed" via voice
- When user input or decision is needed, use the aivisspeech mcp tool to announce "Awaiting your decision" via voice

### Notification Timings
- When asking the user a question
- When all tasks are completed
- When errors or issues occur

1. 验证工具是否被识别

claude mcp list

# Or launch Claude Code and use
/mcp

如果 aivisspeech 显示，设置成功。

💡 提示：为了安全起见，Claude Code不会自动执行命令。如果您忘记启动服务器，工具将不会出现。在开发过程中，请保留上述内容 npx 在终端中运行命令，或使用进程管理器，如 pm2 或 systemd --user 为了持续运行。

使用克劳德桌面

对于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. 下载AivisSpeech https://aivis-project.com/
2. 在本地计算机上启动AivisSpeech
3. 发动机将在默认端口10101上启动
4. 通过访问验证发动机是否正在运行 http://127.0.0.1:10101/docs

📖 其他使用方法

促进地方发展

# Run the MCP server
npm start

# For development with hot reload
npm run dev

# Check if everything is working
npm test

要克隆存储库、安装依赖项和构建：

# Clone repository
git clone https://github.com/shinshin86/mcp-simple-aivisspeech.git
cd mcp-simple-aivisspeech

# Install dependencies
npm install

# Build the project
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+（英特尔和苹果硅）
• Windows 10/11
• Ubuntu 20.04+
• Node.js 18.x、20.x、21.x

🧪 发展

可用脚本

# Development & Building
npm run dev          # Run with hot reload (tsx)
npm run build        # Compile TypeScript to dist/
npm start           # Run compiled server

# Code Quality
npm run lint        # Run ESLint
npm run test        # Run Vitest tests (single run)
npm run test:watch  # Run tests in watch mode
npm run test:ui     # Run tests with UI
npm run test:coverage # Run tests with coverage

# Utilities
npm run clean       # Clean dist/ directory

本地与NPX使用情况

在生产中使用MCP客户端时，请使用 npx @shinshin86/mcp-simple-aivisspeech@latest 在您的MCP配置中。无需本地设置，您始终可以获得最新版本。

对于开发，克隆存储库并使用 npm run dev 用于热重新加载，或 npm run build && npm start 用于测试生产构建。

项目架构

mcp-simple-aivisspeech/
├── src/
│   ├── index.ts                  # MCP server & tool handlers
│   └── aivisspeech-client.ts     # AivisSpeech API client
├── tests/
│   └── aivisspeech-client.test.ts # Unit tests
├── dist/                         # Compiled output
├── docs/                         # Documentation
└── config files                  # TS, ESLint, Vitest configs

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获得许可-请参阅 许可证 文件以获取详细信息。

🤝 贡献

我们欢迎社区的贡献。贡献者可以通过完成以下基本步骤开始：

1. 分叉 存储库
2. 创建 特征分支(git checkout -b feature/amazing-feature)
3. 提交 您的更改(git commit -m 'Add amazing feature')
4. 推 到分行(git push origin feature/amazing-feature)
5. 打开 拉取请求

开发指南

• 遵循现有的Types/ESLint配置
• 添加新功能的测试
• 更新API变更文档
• 确保跨平台兼容性

🙏 致谢

• AivisSpeech项目 对于优秀的TTS发动机
• 模型上下文协议 对于集成框架
• voicex MCP 供参考和借鉴

📞 支持

• 问题-
• 讨论-
• 文件- AivisSpeech API文档

______________________________________________________________________

由...制作❤️ 为日本TTS社区