VoxCPM Audio MCP
Generate local speech, segmented narration, and singing audio via MCP, returning local audio file paths.
speak: synthesize speech or emotional narration from text, with optional control prompt, reference audio, seed, CFG, inference timesteps, WAV/MP3 output, and loudness normalization.speak_segments: synthesize multiple text segments separately and concatenate them with configurable pauses.sing_metadata: generate singing from target metadata, with device selection, pitch shifting, prompt audio/metadata, and WAV/MP3 output.sing_notes: generate singing directly from phonemes, MIDI note pitches, and per-note durations.health: check local model paths, FFmpeg, VoxCPM2 service status, and GPU VRAM availability.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@VoxCPM Audio MCP 用温柔甜美的女声说:今天也要开开心心的哦。"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
VoxCPM Audio MCP
本工作区的部署、飞牛 QQBot 和唱歌服务总览见
C:\Users\lsr\Documents\Codex\2026-09-16\yan\README.md。
本地语音与歌声合成 MCP 服务,把已经安装好的 VoxCPM2 和 SoulX-Singer 暴露给支持 MCP 的客户端。
功能
speak:用 VoxCPM2 生成普通语音、情感旁白或参考音色克隆。speak_segments:把多段文字分别合成,再按设定停顿拼接成完整旁白。list_voice_presets:列出已保存音色。save_voice_preset:保存目标基频、语速、CFG、步数、提示词和参考音频。delete_voice_preset:删除音色预设。sing_metadata:用 SoulX-Singer 读取目标元数据并生成歌声。sing_notes:直接输入音素、MIDI 音高和每字时长生成歌声。health:检查模型路径、FFmpeg、VoxCPM2 服务和 GPU 显存。
服务只返回本地音频文件路径,不包含模型权重。
Related MCP server: mcp-kokoro-tts
Codex 插件
本仓库同时是一个 Codex 插件包:
.codex-plugin/plugin.json 插件清单
.mcp.json 本地 MCP 启动配置
skills/audio/SKILL.md 音频合成技能说明
scripts/launch_mcp.cmd MCP 启动器
scripts/ensure_mcp.ps1 插件环境安装
scripts/start_models.ps1 启动 VoxCPM2 并检查 SoulX-Singer
scripts/stop_models.ps1 停止 VoxCPM2
scripts/manage_cache.ps1 音频缓存统计和清理
scripts/show_logs.ps1 查看 MCP JSONL 日志插件会在 %LOCALAPPDATA%\OpenAI\Codex\Plugins\voxcpm-audio-mcp 创建独立虚拟环境、日志目录和缓存目录,不修改系统 Python。
本地安装
可以使用仓库中的 examples/marketplace.json 作为本地市场配置,或把该仓库作为本地插件目录添加到 Codex。插件安装后,MCP 会通过 scripts/launch_mcp.cmd 自动安装依赖并启动。
也可以直接添加这个 GitHub 仓库作为插件市场:
codex plugin marketplace add ll861181031/voxcpm-audio-mcp热门 Agent 支持
这个仓库同时提供两套兼容格式:
根级
plugin.json+mcp.json:标准 Agent Plugins 布局.codex-plugin/plugin.json+.mcp.json:Codex 兼容布局
已适配的 MCP 客户端包括:
Agent | 状态 |
Codex | 已支持 |
Claude Desktop | 已支持 |
Claude Code | 已支持 |
Cursor | 已支持 |
Windsurf | 已支持 |
Cline | 已支持 |
Continue | 已支持 |
VS Code MCP 客户端 | 已支持 |
通用 stdio MCP 客户端 | 已支持 |
可以生成任意客户端可粘贴的标准 mcpServers JSON:
.\.venv\Scripts\python.exe .\scripts\generate_agent_config.py --agent cursor也可以写入文件:
.\.venv\Scripts\python.exe .\scripts\generate_agent_config.py --agent claude-desktop --output claude-desktop.json详细说明见 docs/agent-support.md。
Python Agent 框架
仓库还提供三个框架接入示例:
examples/frameworks/generic_mcp_client.py
examples/frameworks/openai_agents.py
examples/frameworks/langchain_mcp.py分别对应官方 Python MCP SDK、OpenAI Agents SDK 和 LangChain。
常用维护脚本
.\scripts\start_models.ps1
.\scripts\stop_models.ps1
.\scripts\manage_cache.ps1
.\scripts\manage_cache.ps1 -Clean
.\scripts\show_logs.ps1manage_cache.ps1 默认只做预览;加 -Clean 才会删除超过保留期且超出保留数量的音频文件。
Web 调试页
启动:
.\scripts\start_debug_web.ps1默认地址:http://127.0.0.1:8810
支持:
VoxCPM2 语音合成
target_f0、tempo、cfg_value、inference_timesteps音色预设保存、选用、删除
SoulX-Singer 歌声合成
MCP 日志查看
本地模型、FFmpeg 和显存状态
前置条件
Windows 10/11
Python 3.10+
已安装 VoxCPM2 本地服务,默认
D:\Desktop\VoxCPM2已安装 SoulX-Singer,默认
D:\Desktop\SoulX-Singer可用 FFmpeg,默认
D:\Desktop\VoxCPM2\tools\ffmpeg\bin\ffmpeg.exeNVIDIA GPU 或使用
device=cpu
安装
cd C:\Users\lsr\Documents\Codex\2026-09-16\yan\outputs\voxcpm-audio-mcp
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1安装脚本会创建独立 .venv,不会修改系统 Python。
配置
复制 .env.example 为 .env,按本机路径修改。也可以直接设置环境变量。
关键变量:
VOXCPM_URL=http://127.0.0.1:8808
VOXCPM_START_SCRIPT=D:\Desktop\VoxCPM2\Start-VoxCPM.ps1
SOULX_HOME=D:\Desktop\SoulX-Singer
SOULX_MODEL_PATH=D:\Desktop\SoulX-Singer\pretrained_models\SoulX-Singer\model.pt
FFMPEG=D:\Desktop\VoxCPM2\tools\ffmpeg\bin\ffmpeg.exe
MIN_FREE_VRAM_MB=6000启动 MCP
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\run.ps1或者直接运行:
.\.venv\Scripts\python.exe -m voxcpm_audio_mcp.server该服务使用 stdio transport,适合由 Codex、Claude Desktop 或其他 MCP 客户端启动。
Codex MCP 配置示例
{
"mcpServers": {
"voxcpm-audio": {
"command": "C:\\Users\\lsr\\Documents\\Codex\\2026-09-16\\yan\\outputs\\voxcpm-audio-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "voxcpm_audio_mcp.server"],
"env": {
"VOXCPM_HOME": "D:\\Desktop\\VoxCPM2",
"SOULX_HOME": "D:\\Desktop\\SoulX-Singer",
"FFMPEG": "D:\\Desktop\\VoxCPM2\\tools\\ffmpeg\\bin\\ffmpeg.exe"
}
}
}
}工具示例
普通说话
{
"text": "你好呀,今天也要开开心心的哦。",
"control_instruction": "年轻可爱女声,清亮甜美,亲切自然,带一点笑意。",
"cfg_value": 2.3,
"inference_timesteps": 16,
"output_format": "mp3"
}speak 现在还支持类似“大肥鱼管理台”的数值调音参数:
{
"text": "主人你回来啦,我一直在等你呢。",
"voice_preset": "cute-female",
"target_f0": 260,
"tempo": 1.05,
"cfg_value": 2.3,
"inference_timesteps": 16
}target_f0:目标基频,单位 Hz。tempo:语速倍率,大于 1 更快,小于 1 更慢。cfg_value:提示词权重。inference_timesteps:采样步数。默认调音参数为
target_f0=260、tempo=1.05、cfg_value=2.3、inference_timesteps=16。voice_preset:已保存音色预设名。
分段情感旁白
{
"segments": [
{
"text": "一九三四年十月,赣南秋风卷着细雨。",
"control_instruction": "低沉凝重,缓缓追忆。",
"pause_ms": 900
},
{
"text": "这一送,是百姓的不舍。",
"control_instruction": "深情、克制,句尾放慢。",
"pause_ms": 1200
}
],
"cfg_value": 2.3,
"inference_timesteps": 16
}按音符唱歌
phonemes、note_pitches 和 durations_ms 必须一一对应。<SP> 表示停顿。
{
"phonemes": [
"<SP>",
"zh_yi1", "zh_shan3", "zh_yi1", "zh_shan3",
"zh_liang4", "zh_jing1", "zh_jing1",
"<SP>",
"zh_man3", "zh_tian1", "zh_dou1", "zh_shi4",
"zh_xiao3", "zh_xing1", "zh_xing1"
],
"note_pitches": [0, 60, 60, 67, 67, 69, 69, 67, 0, 65, 65, 64, 64, 62, 62, 60],
"durations_ms": [200, 350, 350, 350, 350, 350, 350, 500, 300, 350, 350, 350, 350, 350, 350, 600],
"text": "<SP> 一 闪 一 闪 亮 晶 晶 <SP> 满 天 都 是 小 星 星",
"device": "auto"
}显存策略
speak需要 VoxCPM2 服务,默认占用约 8GB 显存。sing_notes在device=auto时,如果可用显存低于MIN_FREE_VRAM_MB,会自动回退到 CPU。强制
device=cuda时,显存不足会直接报错,不会抢占正在运行的任务。VoxCPM2 和 SoulX-Singer 不建议同时常驻。当前 12GB 显卡上建议串行调用。
安全与合规
只处理本地文件,不自动上传音频或文本。
参考音频和音色克隆仅用于本人声音或已获授权的声音。
不包含模型权重,模型需由用户自行安装和确认许可证。
MCP 默认通过 stdio 运行,不开放网络端口。
隐私
不收集账号、联系方式或使用统计。
不上传用户文本、参考音频或生成音频。
日志只记录工具名称、参数摘要、输出路径和错误信息,不记录完整文本。
所有模型和输出默认保存在本机。
许可证
MIT。模型权重和第三方模型许可证由各自项目决定,本仓库不包含这些权重。
开发与测试
uv pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytestAvailable Tools
5 toolshealthA
检查本地模型、FFmpeg、VoxCPM2 服务和 GPU 显存状态。
Inputs: no named parameters.
sing_metadataC
用 SoulX-Singer 根据已写好的目标元数据生成带旋律的歌声。
Inputs: target_metadata_path (required), device, control, auto_shift, +5 more.
sing_notesC
用音素、MIDI 音高和每字时长直接生成唱歌,不需要手写完整元数据。
Inputs: phonemes (required), durations_ms (required), note_pitches (required), text, +8 more.
speakC
用本地 VoxCPM2 生成说话或情感旁白。返回音频文件路径。
Inputs: text (required), seed, cfg_value, output_format, +4 more.
speak_segmentsC
把多段文字分别用 VoxCPM2 合成,并按停顿拼接成一条情感旁白。
Inputs: segments (required), seed, cfg_value, output_format, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
speak and speak_segments both synthesize speech, and sing_metadata/sing_notes both synthesize singing; however, descriptions distinguish single vs. multi-segment speech and metadata vs. note-level singing input. An agent can generally tell them apart, though the overlapping pairs may cause occasional misselection.
Most names follow a snake_case verb_noun or verb_object pattern (speak_segments, sing_metadata, sing_notes), with speak as a bare verb and health as a noun utility. The convention is consistent enough to be predictable.
Five tools are well-scoped for an audio synthesis server: two speech modes, two singing modes, and a health check. No obvious bloat or thinness.
The surface covers single and segmented speech, metadata-based and note-based singing, plus system health, which is strong for the stated purpose. Minor gaps like voice/model listing or audio management are not fatal and can be worked around.
Maintenance
Related MCP Connectors
MCP server for Speech-to-Text
AI voice generation: text-to-speech and voice cloning from any MCP client.
Hosted text-to-speech MCP server: 66 voices in 9 languages, long-form narration, podcasts.
MCP server for Text-to-Speech
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to speak by running local voice models using Chatterbox Turbo TTS or Kokoro TTS, with support for voice cloning, paralinguistic tags, and multiple voices.57 npm13MIT
- AlicenseAqualityCmaintenanceEnables MCP clients to synthesize text into speech locally and play it through the machine's audio, with selectable voices and playback speed.262 PyPIApache 2.0
- AlicenseAqualityCmaintenanceEnables any MCP-compatible client to perform local voice cloning and text-to-speech using OmniVoice, including voice profile management, voice design, and an optional ASMR post-processing DSP pipeline.6AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceProvides local speech-to-text and text-to-speech through MCP and HTTP, enabling transcription, voice output, and standalone voice workflows without a gateway.MIT