JinDaGe - NijiVoice MCP Details

article

README

🚀 NijiVoice - MCP 项目文档（中文版）

NijiVoice - MCP 实现了にじボイス API 的 Model Context Protocol (MCP) 版本，借助它，大语言模型（LLM）能够访问 NijiVoice API，轻松实现文本到语音的转换，为语音合成应用提供了便捷的解决方案。

🚀 快速开始

系统要求

Python 3.12 或更高版本
NijiVoice API Key
网络连接

安装指南

# 克隆代码仓库
git clone https://github.com/YOUR_USERNAME/nijivoice-mcp.git
cd nijivoice-mcp

# 安装依赖包
pip install -e .

环境配置

创建 .env 文件，添加以下内容：

NIJIVOICE_API_KEY=你的API密钥
DEFAULT_VOICE_ACTOR_ID=默认使用的声优ID（可选）
LOG_LEVEL=INFO

API Key 可在 NijiVoice 官网获取。

启动 MCP 服务器

python main.py

启动后，MCP 服务器将开始监听来自 LLM 的请求。

✨ 主要特性

使用 NijiVoice API 进行语音合成
获取可用声优信息
查询剩余话费
通过 MCP 接口与 LLM 对接

💻 使用示例

基础用法

LLM 端调用 MCP 服务：

# 获取可用声优列表
actors = await tools.call("actor/get_voice_actors")

# 合成语音
voice_result = await tools.call("voice/generate_voice", {
    "script": "你好，这是 NijiVoice 的测试。",
    "voice_actor_id": "90031163-c497-44f3-a8a6-e45e4d0cb8f6",  # 声优ID
    "speed": 1.0,
    "emotional_level": 0.5,
    "sound_duration": 0.1,
    "format": "mp3"
})

# 查询剩余话费
balance = await tools.call("credit/get_credit_balance")

📚 详细文档

可用的 MCP 工具

声优相关工具

actor/get_voice_actors(): 获取所有可用声优信息。

语音合成工具

voice/generate_voice(): 将文本转换为语音。

项目结构

nijivoice-mcp/
├── niji_mcp/
│   ├── __init__.py
│   ├── api.py          # API 客户端实现
│   ├── exceptions.py   # 异常定义
│   └── models.py       # 数据模型
├── server.py           # MCP 服务器实现
└── utils/              # 工具函数
    ├── __init__.py
    ├── audio_utils.py   # 音频处理工具
    ├── error_handling.py# 错误处理逻辑
    └── retry_logic.py   # 重试机制

测试

# 执行测试
pytest

🔧 技术细节

注意事项与已知问题

开发中项目：功能和规格可能随时变更。
NijiVoice API 变更风险：若其 API 更新，可能导致本项目不兼容。
错误处理不足：某些错误场景的处理尚未完善。
长文本生成超时：处理长文本时有可能发生超时。
部分响应格式未适配：未能完全支持 NijiVoice 的所有 API 响应格式。

故障排除

遇到问题时，可按以下步骤排查：

查看日志文件 nijivoice_mcp.log
确认 API Key 是否正确配置
检查网络连接状态
查看 NijiVoice API 的运行状况

📄 许可证

本项目遵循 MIT License 协议。

致谢

感谢参考了 FastMCP 和 Model Context Protocol，并使用 NijiVoice 的语音合成技术。

⚠️ 重要提示

此项目处于开发阶段，尚未经过全面验证，请勿在生产环境中使用！

NijiVoice