🚀 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 的语音合成技术。
⚠️ 重要提示
此项目处于开发阶段，尚未经过全面验证，请勿在生产环境中使用！