语音转文本MCP服务器

一个模型上下文协议（MCP）服务器，用于使用Rust和OpenAI的Whisper进行语音到文本转录，并支持macOS（Metal/CoreML）、Linux（CUDA）和Windows（CUDA）的硬件加速。

快速开始

# 1. Build the server
cargo build --release

# 2. Download a model
./scripts/download-models.sh

# 3. Add to Claude Code (project scope)
claude mcp add --scope project voice-to-text -- \
  ./target/release/voice-to-text-mcp --mcp-server models/ggml-base.en.bin

# 4. Use in Claude Code
/listen

特性

完整的MCP服务器实现 -符合JSON-RPC 2.0标准的服务器
安静操作 -默认情况下，MCP客户端的输出是干净的（使用 --debug 用于详细日志记录）
硬件加速 -特定于平台的GPU加速：

- macOS：Metal GPU+CoreML（苹果神经引擎）在苹果硅上，Metal在英特尔上 - Linux/Windows：NVIDIA GPU的CUDA GPU加速 - 所有平台上的CPU自动回退

实时音频采集 -现场麦克风录音
文件转录 -处理现有的WAV文件
与跨平台支持 -适用于Linux、macOS和Windows
调试模式 -保存音频文件以进行故障排除

当前状态

✅ 完整的：

使用stdio传输的完整MCP服务器实现
硬件加速Whisper转录（macOS上的Metal/CoreML，Linux/Windows上的CUDA）
实时音频捕获和处理
基于文件的音频转录
全面的命令行界面
带音频文件保存的调试模式
完整的测试套件
模块化架构 关注点分开（音频、耳语、配置、平台）
结构化错误处理 随着 thiserror 为了更好的调试
增强安全性 随着 gag 板条箱替换不安全代码

依赖项

rmcp -模型上下文协议实现
whisper-rs -OpenAI Whisper的Rust绑定（支持Metal/CoreML/CUDA）
cpal -跨平台音频I/O
crossterm -跨平台终端操作（传统键盘控制）
tokio -异步运行时
serde -JSON序列化
anyhow -错误处理
thiserror -结构化错误类型
gag -安全输出抑制

建筑

# Standard build
cargo build --release

# Note: First build with hardware acceleration takes longer:
# - CUDA (Linux/Windows): 6+ minutes due to whisper-rs-sys compilation
# - Metal/CoreML (macOS): 2-3 minutes
# Subsequent builds are much faster

用法

MCP服务器模式

作为MCP服务器运行，以便与MCP客户端集成：

# Run as MCP server with Whisper model
./target/release/voice-to-text-mcp --mcp-server models/ggml-base.en.bin

# Run as MCP server without model (placeholder mode)
./target/release/voice-to-text-mcp --mcp-server

可用的MCP工具：

transcribe_file -将音频文件转录为文本
listen -具有可配置超时和自动停止参数的录音

阻止CLI模式

以阻塞模式运行单次录制操作：

# Download models to models/ directory
cd models
wget https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin
cd ..

# Record audio with default settings (30s max, 2s silence timeout)
./target/release/voice-to-text-mcp models/ggml-base.en.bin

# Record with custom timeouts
./target/release/voice-to-text-mcp --timeout-ms 60000 --silence-timeout-ms 3000 models/ggml-base.en.bin

# Record without auto-stop (record for full timeout)
./target/release/voice-to-text-mcp --no-auto-stop --timeout-ms 10000 models/ggml-base.en.bin

# See all available options
./target/release/voice-to-text-mcp --help

CLI行为：

启动后立即从麦克风录制音频
静音或超时后自动停止
返回转录文本并退出
支持调试模式 --debug 旗帜

调试模式

启用调试模式以保存WAV文件以进行故障排除：

# Using environment variable
VOICE_DEBUG=true ./target/release/voice-to-text-mcp models/ggml-base.en.bin

# Using command line flag
./target/release/voice-to-text-mcp --debug models/ggml-base.en.bin

# Custom debug directory
./target/release/voice-to-text-mcp --debug --debug-dir ./my_debug_folder models/ggml-base.en.bin

# MCP server with debug mode
./target/release/voice-to-text-mcp --mcp-server --debug models/ggml-base.en.bin

# Control what gets saved
./target/release/voice-to-text-mcp --debug --save-raw --save-processed models/ggml-base.en.bin

调试功能：

将原始捕获的音频另存为 audio_YYYYMMDD_HHMMSS_raw.wav
将处理后的音频另存为 audio_YYYYMMDD_HHMMSS_processed.wav
自动调试目录创建
基于时间戳的文件命名
有助于排除音频问题和Whisper输入验证

型号下载

使用我们的交互式下载脚本（推荐）：

./scripts/download-models.sh

该脚本提供：

🎯 按用例提供模型推荐的交互式菜单
📊 型号尺寸、描述和性能信息
✅ 自动检测现有模型（避免重新下载）
🔄 恢复中断下载的功能
💾 下载前进行磁盘空间验证
🌈 用户友好的彩色界面

快速建议：

发展: ggml-tiny.en.bin （75MB）-测试速度最快
大多数用户: ggml-base.en.bin （142MB）-最佳平衡⭐
高质量: ggml-small.en.bin （466MB）-精度更高
多语言: ggml-base.bin （142MB）-适合非英语人士

手动下载替代方案：

cd models/
wget https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin

测试

运行完整的测试套件：

cargo test

该项目包括：

单元测试 （17项测试）-核心功能和硬件加速测试
集成测试 （5项测试）-端到端工作流程和加速性能测试
基于属性的测试 （2个测试）-随机输入验证
MCP接口测试 （14项测试）-全面覆盖的完整MCP协议测试

检查硬件加速

要验证平台的加速配置：

# Check platform detection and acceleration features
cargo test test_hardware_acceleration_runtime_info -- --nocapture

# Run acceleration integration tests
cargo test test_hardware_acceleration -- --nocapture

测试覆盖范围包括：

服务创建和状态管理
音频捕获和处理
录制工作流程（启动/停止周期）
并行操作
边缘情况和错误条件
Whisper模型加载和转录
音频归一化和预处理
调试配置和WAV文件保存
基于时间戳的文件命名

MCP集成

此服务器可以与任何兼容MCP的客户端集成。

Claude代码集成

语音转文本MCP服务器与Claude Code集成，直接在您的开发工作流程中提供语音转文本转录功能。这允许您使用语音口述代码、注释、文档或任何文本内容。

克劳德代码的先决条件

已安装Claude Code CLI 支持MCP
内置语音转文本mcp二进制文件 （见上文建筑部分）
Whisper型号已下载 （见上文模型下载部分）
麦克风 在您的系统上可用

安装选项

Option 1: Project-Level Installation (Recommended for Development)

为特定项目安装MCP服务器。这使得语音转文本功能与您需要的项目隔离开来。

# From the voice-to-text-mcp repository directory
# Build the project first
cargo build --release

# Add to Claude Code for this project only
claude mcp add --scope project voice-to-text -- \
  ./target/release/voice-to-text-mcp --mcp-server models/ggml-base.en.bin

# Verify installation
claude mcp list --scope project

用例：非常适合您在这个语音转文本项目或其他经常需要口述代码或文档的项目中工作。

Option 2: User-Level Installation (Global Access)

为您的用户帐户全局安装MCP服务器。这使得语音转文本在所有Claude Code会话中都可用。

# From the voice-to-text-mcp repository directory
# Get absolute paths for the binary and model
BINARY_PATH=$(pwd)/target/release/voice-to-text-mcp
MODEL_PATH=$(pwd)/models/ggml-base.en.bin

# Add to Claude Code globally
claude mcp add --scope user voice-to-text -- \
  "$BINARY_PATH" --mcp-server "$MODEL_PATH"

# Verify installation
claude mcp list --scope user

用例：当您希望在所有开发项目中都提供语音转文本功能，并且不想为每个项目进行配置时，这是理想的选择。

Option 3: Development with Debug Mode

用于调试或处理语音到文本服务器本身时：

# Project-level with debug enabled
claude mcp add --scope project voice-to-text-debug -- \
  ./target/release/voice-to-text-mcp --mcp-server --debug models/ggml-base.en.bin

# Check debug output
claude mcp list --scope project

Claude代码的基本用法

安装后，在Claude Code中使用以下命令：

# Record with default settings (30s max, 2s silence timeout)
/listen

# Record with custom timeout (60 seconds)
/listen timeout_ms=60000

# Record with longer silence timeout (5 seconds)
/listen silence_timeout_ms=5000

# Record for full duration without auto-stop
/listen timeout_ms=10000 auto_stop=false

# Transcribe an existing audio file
transcribe_file file_path="debug/audio_20250112_143022_raw.wav"

实际使用场景

Dictating Code

# Record your voice describing the code you want
/listen

# Example transcription result:
# "Create a function called calculate total that takes a list of numbers and returns the sum"

# Then ask Claude to convert to code:
# Convert this to Python code: "Create a function called calculate total that takes a list of numbers and returns the sum"

Code Documentation

# Dictate function documentation
/listen timeout_ms=45000

# Example result:
# "This function implements a binary search algorithm. It takes a sorted array and a target value as parameters. Returns the index of the target if found, otherwise returns negative one."

Commit Messages

# Dictate commit messages
/listen timeout_ms=15000

# Example result:
# "Fix authentication bug in user login flow and add unit tests for edge cases"

Issue Descriptions

# Describe bugs or features
/listen timeout_ms=60000

# Example result:
# "When users click the submit button on the contact form, the page doesn't show any loading indicator and sometimes the form gets submitted multiple times causing duplicate entries in the database"

工作流集成示例

Voice-Driven Development Workflow

# 1. Start with a voice description of what you want to build
/listen timeout_ms=45000
# Result: "I need to create a REST API endpoint that accepts user registration data validates the email format checks if the user already exists and saves the new user to the database"

# 2. Ask Claude to create the implementation
# Based on this description, create a Python Flask endpoint for user registration

# 3. Dictate test cases
/listen timeout_ms=30000
# Result: "Test with valid email, test with invalid email format, test with duplicate email, test with missing required fields"

# 4. Ask Claude to implement the tests
# Create pytest test cases for these scenarios

Documentation Workflow

# 1. Dictate API documentation
/listen timeout_ms=60000
# Result: "The get users endpoint returns a paginated list of users. It accepts optional query parameters page for page number limit for items per page and search for filtering by username or email"

# 2. Format as documentation
# Convert this to OpenAPI/Swagger documentation format

# 3. Add implementation notes
/listen timeout_ms=30000
# Result: "Note that this endpoint requires authentication and users can only see other users if they have admin role otherwise they only see their own profile"

配置管理

# View current configuration
claude mcp list

# List project-specific servers
claude mcp list --scope project

# List user-level servers
claude mcp list --scope user

# Remove existing configuration
claude mcp remove --scope project voice-to-text

# Update configuration
claude mcp add --scope project voice-to-text -- \
  ./target/release/voice-to-text-mcp --mcp-server --debug models/ggml-base.en.bin

Claude代码集成故障排除

Common Issues and Solutions

未找到MCP服务器：

# Error: "MCP server not found"
# Solution: Verify the binary path is correct
ls -la target/release/voice-to-text-mcp

# Re-add with correct path
claude mcp remove --scope project voice-to-text
claude mcp add --scope project voice-to-text -- \
  ./target/release/voice-to-text-mcp --mcp-server models/ggml-base.en.bin

找不到模型文件：

# Error: "Model file not found"
# Solution: Verify model exists and path is correct
ls -la models/ggml-base.en.bin

# Download model if missing
./scripts/download-models.sh

音频设备问题：

# Error: "No input device available"
# Solution: Check system audio settings and permissions

# Test with debug mode to see detailed errors
claude mcp remove --scope project voice-to-text
claude mcp add --scope project voice-to-text -- \
  ./target/release/voice-to-text-mcp --mcp-server --debug models/ggml-base.en.bin

# Try recording to see debug output
/listen

权限问题：

# Error: "Permission denied"
# Solution: Ensure binary is executable
chmod +x target/release/voice-to-text-mcp

# On macOS, you might need to allow the binary in Security & Privacy settings

语音输入的最佳实践

清晰的演讲：在安静的环境中以适中的语速清晰地说话
结构化听写：录制前整理思路
提供上下文：在听写中包含上下文（例如，“对于Python Flask应用程序…”）
迭代精化：从基本结构开始，然后添加细节和边缘案例

性能优化

按用例选择模型：

型号	尺寸	速度	精度	最适合
`ggml-tiny.en.bin`	75MB	最快	良好	快速笔记，原型制作
`ggml-base.en.bin`	142MB	快速	更好	一般开发工作
`ggml-small.en.bin`	466MB	较慢	最好	文档，正式内容

录制设置优化：

# For quick commands (shorter timeout)
/listen timeout_ms=10000 silence_timeout_ms=1000

# For detailed explanations (longer timeout)
/listen timeout_ms=120000 silence_timeout_ms=3000

# For continuous dictation (no auto-stop)
/listen timeout_ms=300000 auto_stop=false

其他MCP客户端

为了与其他MCP兼容客户端（如Claude Desktop）集成，您可以使用标准MCP配置：

基础 .mcp.json 设置：

{
  "mcpServers": {
    "voice-to-text": {
      "command": "./target/release/voice-to-text-mcp",
      "args": ["--mcp-server", "models/ggml-base.en.bin"]
    }
  }
}

在调试模式下：

{
  "mcpServers": {
    "voice-to-text": {
      "command": "./target/release/voice-to-text-mcp",
      "args": ["--mcp-server", "--debug", "models/ggml-base.en.bin"]
    }
  }
}

MCP工具调用示例

// Transcribe a file
{
  "method": "tools/call",
  "params": {
    "name": "transcribe_file",
    "arguments": {
      "file_path": "debug/audio_20250710_194139_raw.wav"
    }
  }
}

// Record audio with default settings (30s max, 2s silence timeout, auto-stop enabled)
{
  "method": "tools/call", 
  "params": {
    "name": "listen",
    "arguments": {}
  }
}

// Record audio with custom timeout (60 seconds)
{
  "method": "tools/call", 
  "params": {
    "name": "listen",
    "arguments": {
      "timeout_ms": 60000
    }
  }
}

// Record audio with custom silence timeout (3 seconds)
{
  "method": "tools/call",
  "params": {
    "name": "listen", 
    "arguments": {
      "silence_timeout_ms": 3000
    }
  }
}

// Record for full timeout without auto-stop
{
  "method": "tools/call",
  "params": {
    "name": "listen",
    "arguments": {
      "timeout_ms": 10000,
      "auto_stop": false
    }
  }
}

发展

该实现提供了一个完整的语音转文本MCP服务器。未来的增强功能可能包括：

音频格式支持 -支持MP3、OGG和其他格式
流式转录 -捕获音频时的实时转录
多语言模型 -自动语言检测
配置API -音频设备和型号的运行时配置

系统要求

必需

锈蚀1.70+
音频输入设备（麦克风）
Linux上的ALSA开发库(libasound2-dev 在Ubuntu/Debian上）

硬件加速（可选）

macOS

苹果硅（M1/M2/M3）：自动金属GPU+CoreML（苹果神经引擎）加速
英特尔Mac：自动金属GPU加速
无需额外安装-使用内置的macOS框架

Linux/Windows

英伟达GPU 支持CUDA
CUDA工具包 11.0+已安装

所有平台

如果硬件加速不可用，系统会自动回退到CPU处理
CPU回退提供相同的功能，但转录速度较慢

安装说明

构建时间

首次使用硬件加速进行构建需要更长的时间：

- 流处理器 （Linux/Windows）：6+分钟 - 金属/CoreML （macOS）：2-3分钟

后续构建要快得多

平台兼容性

macOS：使用特定于平台的兼容层来处理CoreAudio线程约束
Linux/Windows：带CUDA加速的标准螺纹模型
所有平台都保持相同的功能和API

业绩说明

macOS苹果硅：使用CoreML速度提高3倍，使用NEON SIMD速度提高2-3倍
macOS英特尔：Metal GPU加速速度提高1.5-2倍
Linux/Windows：CUDA GPU加速速度提高2-4倍
CoreML注释：第一次运行需要15-20分钟进行模型编译，然后缓存以备将来使用

建筑

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │───▶│   MCP Server    │───▶│ Whisper Engine  │
│ (Claude, VSCode)│    │   (JSON-RPC)    │    │ (CUDA/CPU)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │ Audio Capture   │
                       │ & Processing    │
                       │     (cpal)      │
                       └─────────────────┘

组件

MCP服务器：带stdio传输的JSON-RPC 2.0服务器
Whisper发动机：硬件加速语音识别（Metal/CoreML/CUDA），CPU回退
音频管道：实时捕获、重采样和预处理
调试系统：音频文件保存和分析工具
模型下载器：交互式脚本，便于Whisper模型管理(scripts/download-models.sh)

项目结构

voice-to-text-mcp/
├── src/                     # Rust source code
│   ├── lib.rs              # Main service coordination
│   ├── main.rs             # CLI entry point
│   ├── mcp_server.rs       # MCP protocol implementation
│   ├── platform_compat.rs  # Cross-platform compatibility layer
│   ├── audio.rs            # Audio capture and processing
│   ├── whisper.rs          # Whisper transcription logic
│   ├── config.rs           # Configuration and constants
│   ├── platform.rs         # Platform-specific implementations
│   ├── keyboard.rs         # Keyboard control functionality (legacy)
│   └── error.rs            # Structured error types
├── scripts/                # Utility scripts
│   └── download-models.sh  # Interactive model downloader
├── models/                 # Whisper model files (downloaded)
├── tests/                  # Test suites
└── target/                 # Build artifacts

许可证

这个项目是开源的。请参阅许可证文件了解详细信息。

Voice To Text MCP

快速接入

详细介绍