voxtral-mcp Skill 技能

voxtral-mcp 是把 Mistral Voxtral 4B TTS 模型（MLX 4-bit 量化）包成 MCP Server 的本地语音合成工具，可被 Claude Code / Claude Desktop / Cursor 等任何 MCP 客户端直接调用 speak(text, voice?) 让 Agent「开口说话」。它在 Apple Silicon 上 ~2.4× 实时合成、~1s 端到端首音频延迟（TTFA）、9 种语言 + 20 个预设音色。

> ⚠️ 许可提示：Voxtral 模型本身由 Mistral 以 CC BY-NC 4.0 授权 —— 仅限非商用场景；本包装代码是 MIT 开源。商业部署请评估 Mistral 商用授权或选用其他 TTS 后端。

核心能力

• Mistral Voxtral 4B TTS（MLX 4-bit）：4B 参数、4-bit 量化后约 2.5GB 磁盘、加载后 ~3GB 常驻内存；Apple Silicon 上约 2.4× 实时生成速度。
• ~1s TTFA（Time-To-First-Audio）：通过 mlx-audio 的 stream=True 原生流式生成，按 VOXTRAL_STREAMING_INTERVAL（默认 1.0s）切分音频块输出，避免「等整段合成完才出声」。
• 9 语言 / 20 音色：英、法、德、西、意、葡、荷、印地、阿拉伯，覆盖 casual / neutral / cheerful 等风格；传 voice="fr_female" 即可切换音色。
• 3 个 MCP 工具：speak(text, voice?, interrupt?) 流式合成并入队后台播放（默认顺序排队，含跨 turn）；stop_speaking() 立即停止 + 清空队列 + 取消在飞生成；status() 上报模型加载状态、队列深度、采样率、最近错误。
• 非阻塞 gap-free 播放：speak() 立刻返回，模型流式生成 → 通过 sounddevice 写模式播放，多个 speak 调用之间无音频空隙。
• 中断 / 切换语义清晰：想立刻打断当前朗读 + 切新内容，传 interrupt=True；想完整静音用 stop_speaking()；中间 turn 打断 + 新朗读用 speak(..., interrupt=True)，三种意图各自对应明确工具。
• Claude Code 一键插件：通过 /plugin marketplace add Vincweb/voxtral-mcp + /plugin install voicebox@vincweb-tools 一次拉齐 MCP 接线 + /voice-mode skill，无需手动编辑 .mcp.json。

安装配置

• 临时试用：uvx voxtral-mcp --help，无需安装即可查看用法。
• 持久安装：uv tool install voxtral-mcp，全局可用 voxtral-mcp 命令。
• 注册到 MCP 客户端：在 .mcp.json 里加：

  { "mcpServers": { "voxtral": { "command": "uvx", "args": ["voxtral-mcp"] } } }

  Docker / Linux 客户端需自备 Apple Silicon 兼容层。

• 环境变量（写在 .mcp.json 的 env 块）：VOXTRAL_MODEL（默认 mlx-community/Voxtral-4B-TTS-2603-mlx-4bit，可换 4-bit / 6-bit / bf16 任意 HF 上的 Voxtral MLX 变体）、VOXTRAL_STREAMING_INTERVAL（默认 1.0 秒 / 流式块）、VOXTRAL_MAX_TOKENS（默认 4096，生成上限单位是音频 token 不是字符）、VOXTRAL_SAMPLE_RATE（默认 24000 Hz）。
• 硬件依赖：macOS Apple Silicon（M1 / M2 / M3 / M4 必需，MLX 不支持 Intel）、≥16 GB RAM（4-bit 模型 ~3GB 常驻）、Python 3.10 – 3.14。
• 首次加载：首次 speak() 触发模型下载（~2.5GB），完成后本地常驻，无需再联网。

使用步骤

1. 安装 MCP server：uv tool install voxtral-mcp，或在临时场景用 uvx voxtral-mcp。
2. 注册到客户端：编辑 .mcp.json 添加 voxtral server 段，重启 Claude Code / Cursor / Claude Desktop。
3. 验证加载：在客户端里调 status()，确认模型加载完成（首次会触发 ~2.5GB 模型下载）。
4. 首次朗读：调用 speak("Hello world")，默认 casual_female 英文音色，~1 秒后开始播放流式音频。
5. 切换语言 / 音色：传 voice="fr_female" 切法语女声、voice="es_male" 切西班牙男声 等 20 个选项。
6. Claude Code 用户走捷径：在 Claude Code 里 /plugin marketplace add Vincweb/voxtral-mcp + /plugin install voicebox@vincweb-tools，自动完成 MCP 接线 + /voice-mode skill 注入；之后直接说「voice mode on」就能切换到语音交互。
7. 打断 / 静音：要立刻切换朗读内容用 speak("新文本", interrupt=True)；要彻底静音用 stop_speaking()；想看当前播放 / 队列状态用 status()。

适用场景

• AI Agent 语音化：给 Claude Code / Claude Desktop 加语音输出，Agent 回复可以直接朗读。
• macOS 本地化 TTS：拒绝云端 TTS（OpenAI / ElevenLabs），全程本地、零云调用、低延迟。
• 多语言助手：客服 / 教学 / 演示 Agent 需要英、法、德、西、意、葡、荷、印地、阿拉伯 9 语言覆盖。
• 流式对话场景：长回答不必等全部生成完才出声，TTFA ~1s 让用户能即时听到开始。
• 快捷音色切换：在 casual_male / neutral_female / cheerful_female / fr_male 等之间按场景切换风格。
• 断网 / 隐私场景：所有合成在 Apple Silicon 本地完成，无云端调用、无 API key、无用量计费。
• Claude Code 插件分发：作为 Claude Code Plugin Marketplace 一员，直接 /plugin install voicebox@vincweb-tools 拉齐。

适用人群

• macOS Apple Silicon 用户（M1 / M3 / M4 等）
• 想要本地化、零云调用 TTS 的开发者
• 给 Claude Code / Cursor 加语音能力的 Agent 创作者
• 多语言（特别是欧洲 9 国 + 印地 / 阿拉伯）应用 owner
• 商业部署前需评估 Mistral CC BY-NC 4.0 授权边界的产品方

工作原理

voxtral-mcp 把 mlx-audio 的 Mistral Voxtral 4B TTS（4-bit MLX 量化版本）包装为本地 stdio MCP server，通过 MCP tools/list 暴露 speak / stop_speaking / status 三个工具。speak(text, voice?, interrupt?) 调用 mlx-audio 的流式 TTS（stream=True），把音频按 VOXTRAL_STREAMING_INTERVAL（默认 1.0s）切块，通过 sounddevice write-mode 写到输出，全程 ~2.4× 实时合成速度在 Apple Silicon 上。TTFA ~1s 来自流式分块 + 后台排队 + 立即返回；多 speak 调用默认顺序排队跨 turn 播放，传 interrupt=True 时先 stop + 清空队列再开始新内容。模型本身只跑 Apple Silicon MLX 后端（不支持 Intel / CUDA），加载后 ~3GB 常驻内存；首次 speak() 触发从 Hugging Face 下载 mlx-community/Voxtral-4B-TTS-2603-mlx-4bit 模型（~2.5GB），完成后无网络依赖。

官方链接

• PyPI 包：https://pypi.org/project/voxtral-mcp/
• 源码仓库：https://github.com/Vincweb/voxtral-mcp
• README（含 20 音色表 + 环境变量 + Claude Code 插件用法）：https://github.com/Vincweb/voxtral-mcp#readme
• 模型：mlx-community/Voxtral-4B-TTS-2603-mlx-4bit（HuggingFace）
• 许可：本包装 MIT，Voxtral 模型 CC BY-NC 4.0（非商用）