mcp简单ai语音服务器

Name: mcp简单ai语音服务器
Author: shinshin86

作者：shinshin868 星标更新：2025-07-01

安装使用来源：spider==github.com

项目介绍

MCP Simple AivisSpeech

项目Logo

English | 日本語

🙏 特别感谢
本项目基于@t09tanaka的mcp-simple-voicevox。
我们非常感谢他们为创建适用于VOICEVOX的原始MCP服务器所做的出色工作，这为本次AivisSpeech适配奠定了基础。

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

✨ 特性

文本到语音转换 - 使用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确保您始终自动获取最新版本。无需手动更新。

在使用Claude Code的终端之外的单独终端中手动启动AivisSpeech MCP服务器

npx @shinshin86/mcp-simple-aivisspeech@latest

将MCP服务器注册到Claude Code

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.1:10101 -- npx @shinshin86/mcp-simple-aivisspeech@latest

您还可以在CLAUDE.md文件中添加语音通知，以自动化任务完成通知：

## 任务完成行为
- 当所有任务完成后，始终使用aivisspeech mcp工具通过语音宣布“任务已完成”
- 当需要用户输入或决策时，使用aivisspeech mcp工具通过语音宣布“等待您的决策”

### 通知时间
- 当询问用户问题时
- 当所有任务完成后
- 当出现错误或问题时

验证工具是否被识别

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在本地运行。

从https://aivis-project.com/下载AivisSpeech
在本地机器上启动AivisSpeech
引擎将在默认端口10101上启动
通过访问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	`afplay`	内置（无需额外设置）
Windows	PowerShell Media.SoundPlayer	Windows PowerShell
Linux	`aplay`	ALSA utils (`sudo apt install alsa-utils`)

测试环境

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/                         # 文档
└── 配置文件                      # TS、ESLint、Vitest配置

API客户端架构

AivisSpeechClient类提供了全面的功能，提供以下几个关键能力：

HTTP客户端 - 基于Axios的API通信
错误处理 - 全面的错误捕获和报告
类型安全性 - 所有API响应的完整TypeScript接口
连接管理 - 健康检查和状态监控

添加新功能

新工具：在src/index.ts中的CallToolRequestSchema添加处理器
API方法：扩展AivisSpeechClient类
类型：更新aivisspeech-client.ts中的接口
测试：添加相应的测试用例

🔧 故障排除

常见问题

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文件。

🤝 贡献

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

分叉仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开拉取请求

开发指南

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

🙏 致谢

AivisSpeech项目为优秀的TTS引擎
模型上下文协议为集成框架
VOICEVOX MCP为灵感和参考

📞 支持

问题 - GitHub问题
讨论 - GitHub讨论
文档 - AivisSpeech API文档

为日语TTS社区制作，充满爱心