Sc MCP Voice Server

🎤 MCP语音服务器

AI编码代理的免费本地优先语音。 与Claude Code、KiloCode、Codex或任何兼容MCP的CLI交谈——由您机器上运行的Whisper+Kokoro提供支持。不需要API密钥。没有云。没有成本。

需要云语音吗？只需一个命令即可动态切换提供程序。

# In Claude Code chat:
/voice                                    # speak → auto-transcribe (free, local)
/voice --provider elevenlabs              # switch to ElevenLabs mid-conversation
/voice --provider openai --voice shimmer  # or OpenAI
/voice --provider local                   # back to free

______________________________________________________________________

这是什么

MCP（模型上下文协议）服务器，为任何兼容的AI编码代理提供语音接口。它处理：

• 语音转文本（STT） --Whisper将您的声音转录为文本
• 文本转语音（TTS） --Kokoro会把特工的回应告诉你
• 语音活动检测（VAD） --Silero VAD自动检测您何时停止说话
• 提供商切换 --运行时本地和云提供商之间的交换

它作为CLI工具自动生成的后台进程运行。你从不手动启动它。

为什么

• macOS听写已损坏且不可靠
• 云语音API需要花钱，并将您的音频发送给第三方
• 现有的语音工具没有与编码代理集成
• 你应该能够免提与你的AI配对程序员交谈

______________________________________________________________________

提供商

*\*ElevenLabs模式仍然使用本地Whisper进行STT以节省资金。*

本地优先策略的年度成本： 0-18美元/年.

______________________________________________________________________

建筑

┌──────────────────────────────────────────────────────────┐
│            MCP Voice Server (auto-spawned)                │
│                                                          │
│  Transport:  stdio (Claude Code)  or  HTTP :9000 (debug) │
│                                                          │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐         │
│  │   LOCAL     │  │ ELEVENLABS │  │   OPENAI   │         │
│  │ Whisper+    │  │ Whisper+   │  │ OpenAI+    │         │
│  │ Kokoro      │  │ 11Labs TTS │  │ OpenAI TTS │         │
│  └────────────┘  └────────────┘  └────────────┘         │
│         ↕ fallback chain: local → elevenlabs → openai    │
│                                                          │
│  Audio Pipeline:                                         │
│  Mic (sox) → VAD (Silero) → STT → Agent → TTS → Speaker │
└──────────────────────────────────────────────────────────┘
        ↑               ↑               ↑
   Claude Code      KiloCode        Codex / Any MCP Client

______________________________________________________________________

快速开始

# 1. Clone the repo
git clone https://github.com/shane9coy/sc-mcp-voice-server.git
cd mcp-voice-server

# 2. Install dependencies
bash install.sh

# 3. Add to your AI coding tool (see INSTALL.md for full details)
#    Add to .claude/settings.json:
#    "voice": { "command": "node", "args": ["/path/to/mcp-voice-server/src/index.js"] }

# 4. Make sure Whisper + Kokoro are running
#    Whisper: http://localhost:2022
#    Kokoro:  http://localhost:8880

# 5. Test it
node src/index.js --http
curl http://localhost:9000/api/health

→ See 安装.md 获取完整的分步指南。

______________________________________________________________________

用法

使用克劳德代码

claude --voice

然后在聊天中：

/voice                          # Listen → transcribe → return text
/voice speak "Hello world"      # Speak text aloud
/voice --provider elevenlabs    # Switch to ElevenLabs
/voice --provider local         # Switch back to free
/voice status                   # Show health of all providers

使用KiloCode/OpenCode

kilocode --voice

相同 /voice 命令工作。

独立（HTTP模式）

# Start the HTTP debug server
node src/index.js --http

# Health check
curl http://localhost:9000/api/health

# Speak
curl -X POST http://localhost:9000/api/speak \
  -H 'Content-Type: application/json' \
  -d '{"text": "Voice server online."}'

# Switch provider
curl -X POST http://localhost:9000/api/switch \
  -H 'Content-Type: application/json' \
  -d '{"provider": "elevenlabs"}'

# Listen (records mic, transcribes, returns text)
curl -X POST http://localhost:9000/api/listen

远程SSH

# Cloud providers auto-detected when SSH'd
ssh user@remote
voice --provider elevenlabs     # works without local services

# Or tunnel local services through SSH
ssh -L 2022:localhost:2022 -L 8880:localhost:8880 user@remote
voice --provider local          # local Whisper/Kokoro via tunnel

______________________________________________________________________

MCP工具

服务器公开了任何MCP客户端都可以调用的5个工具：

语音监听

{
  "max_duration_seconds": 30,
  "language": "en",
  "use_vad": true,
  "model": "base"
}
// Returns: { "transcript": "what you said", "provider": "local", "model": "base" }

语音_峰值

{
  "text": "Hello world",
  "voice": "af_heart",
  "model": "kokoro-v0.19"
}
// Returns: { "success": true, "provider": "local", "voice": "af_heart" }

语音开关

{
  "provider": "elevenlabs",
  "model": "eleven_turbo_v2",
  "voice": "antoni"
}
// Returns: { "success": true, "activeProvider": "elevenlabs", "info": {...} }

______________________________________________________________________

配置

配置文件位置

~/.voice-mcp/config.json --首次运行时自动创建。

超越优先级（最高获胜）

1. CLI标志： --provider elevenlabs --model eleven_turbo_v2 --voice antoni
2. 项目配置： .claude/voice-config.json 或 .opencode/voice-config.json
3. 用户配置： ~/.voice-mcp/config.json
4. 内置默认值

默认配置

{
  "defaultProvider": "local",
  "vad": {
    "enabled": true,
    "silenceThresholdMs": 800,
    "speechPadMs": 300
  },
  "audio": {
    "sampleRate": 16000,
    "channels": 1,
    "format": "wav",
    "captureDevice": "default",
    "playbackCommand": "auto"
  },
  "providers": {
    "local": {
      "stt": { "url": "http://localhost:2022/v1/audio/transcriptions", "model": "base" },
      "tts": { "url": "http://localhost:8880/v1/audio/speech", "model": "kokoro-v0.19", "voice": "af_heart" },
      "requiresAuth": false
    },
    "elevenlabs": {
      "stt": { "url": "http://localhost:2022/v1/audio/transcriptions", "model": "base" },
      "tts": { "url": "https://api.elevenlabs.io/v1", "model": "eleven_monolingual_v1", "voice": "rachel" },
      "requiresAuth": true,
      "envKey": "ELEVENLABS_API_KEY"
    },
    "openai": {
      "stt": { "url": "https://api.openai.com/v1/audio/transcriptions", "model": "whisper-1" },
      "tts": { "url": "https://api.openai.com/v1/audio/speech", "model": "tts-1", "voice": "nova" },
      "requiresAuth": true,
      "envKey": "OPENAI_API_KEY"
    }
  },
  "fallbackChain": {
    "local": ["local", "elevenlabs", "openai"],
    "elevenlabs": ["elevenlabs", "local", "openai"],
    "openai": ["openai", "elevenlabs", "local"]
  }
}

更改默认值

编辑 ~/.voice-mcp/config.json 要更改默认模式或语音：

# Example: switch default local Whisper model to "medium" for better accuracy
# Edit ~/.voice-mcp/config.json → providers.local.stt.model = "medium"

或者通过创建来覆盖每个项目 .claude/voice-config.json 在您的项目根目录中。

______________________________________________________________________

ElevenLabs的声音

/voice --provider elevenlabs --voice antoni

______________________________________________________________________

OpenAI语音

可用语音： alloy, echo, fable, onyx, nova, shimmer

可用型号： tts-1 （快速、廉价）， tts-1-hd （更高的质量，2倍的成本）

/voice --provider openai --model tts-1-hd --voice shimmer

______________________________________________________________________

项目结构

mcp-voice-server/
├── README.md                          ← you are here
├── INSTALL.md                         ← step-by-step install guide
├── LICENSE
├── package.json
├── install.sh                         ← automated dependency installer
├── vad-record.py                      ← Python VAD helper script
├── src/
│   ├── index.js                       ← entry point (stdio MCP or HTTP)
│   ├── mcp-server.js                  ← MCP tool definitions + handlers
│   ├── http-server.js                 ← Express REST API (standalone/debug)
│   ├── config.js                      ← config loader with merge logic
│   ├── providers/
│   │   ├── base-provider.js           ← abstract interface
│   │   ├── local-provider.js          ← Whisper + Kokoro
│   │   ├── elevenlabs-provider.js     ← ElevenLabs API
│   │   └── openai-provider.js         ← OpenAI API
│   ├── audio/
│   │   ├── capture.js                 ← mic recording via sox
│   │   ├── vad.js                     ← Silero VAD integration
│   │   ├── playback.js               ← cross-platform audio playback
│   │   └── convert.js                 ← ffmpeg format conversion
│   └── utils/
│       ├── health.js                  ← service health checks
│       ├── logger.js                  ← structured logging
│       └── errors.js                  ← custom error types
└── tests/
    └── smoke-test.sh                  ← basic integration tests

______________________________________________________________________

需求

______________________________________________________________________

故障排除

______________________________________________________________________

贡献

PR欢迎。该架构旨在使添加新提供者变得容易——只需扩展即可 BaseProvider 并实施 transcribe(), speak()，以及 healthCheck().

______________________________________________________________________

许可证

麻省理工学院