Voice Transcriber MCP Server

语音转录 MCP 服务

使用 Groq Whisper API（whisper-large-v3）自动转录 Google Chat 语音消息的 MCP 服务。无需本地 GPU。

当 Claude Code 在 Google Chat 消息中遇到音频附件时，此服务会立即转录，无需请求确认。

功能

• 按 URL 转录 Google Chat 语音消息（自动）
• 转录本地音频文件（mp3、m4a、wav、ogg、flac、webm、aac）
• 使用 Groq Whisper API（免费套餐，速度快，基于云端）
• 复用 Google Chat OAuth2 凭据（无需单独进行 Google 身份验证）

前提条件

1. Groq API 密钥（免费）

1. 前往 console.groq.com/keys
2. 创建免费账户
3. 生成 API 密钥
4. 将其设置为 MCP 配置中的 GROQ_API_KEY（见下文）

2. Google Chat OAuth2 令牌

此服务需要有效的 Google Chat OAuth2 令牌（token.json），以获取消息并下载音频附件。

如果你已经在使用 Google Chat MCP 服务（例如 multi-chat-mcp-server），则令牌已存在。默认路径：

~/tools/multi-chat-mcp-server/src/providers/google_chat/token.json

如果令牌位于其他位置，请设置 GCHAT_TOKEN_PATH 环境变量。

如果你还没有 Google Chat 令牌，则需要：

1. 创建一个启用了 Chat API 的 Google Cloud 项目
2. 创建 OAuth2 凭据（桌面应用）
3. 运行 OAuth 流程，使用以下范围生成 token.json：
   • https://www.googleapis.com/auth/chat.messages.readonly
   • https://www.googleapis.com/auth/chat.spaces.readonly

3. uv（Python 包管理器）

操作系统	命令
Linux / macOS / WSL	curl -LsSf https://astral.sh/uv/install.sh | sh
Windows	powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

验证：uv --version

安装

git clone https://github.com/fgasparetto/voice-transcriber-mcp.git
cd voice-transcriber-mcp
uv sync

配置

添加到你的 Claude Code MCP 配置（.mcp.json 或 ~/.claude.json）：

{
  "mcpServers": {
    "voice-transcriber": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory", "/path/to/voice-transcriber-mcp",
        "run", "python", "server.py"
      ],
      "env": {
        "GROQ_API_KEY": "gsk_your_groq_api_key_here"
      }
    }
  }
}

替换：

• 将 /path/to/voice-transcriber-mcp 替换为实际的克隆目录
• 将 gsk_your_groq_api_key_here 替换为你的 Groq API 密钥

环境变量

变量	必需	默认值	描述
GROQ_API_KEY	是	—	Groq API 密钥（免费获取）
GCHAT_TOKEN_PATH	否	~/tools/multi-chat-mcp-server/src/providers/google_chat/token.json	Google Chat OAuth2 令牌的路径

工具

transcribe_voice_message

转录来自 Google Chat 的语音消息。Claude 遇到音频附件时会自动调用。

transcribe_voice_message(
  message_url="https://chat.google.com/dm/SPACE/THREAD/MSG",
  language="it"
)

transcribe_audio_file

转录本地音频文件。

transcribe_audio_file(
  file_path="/tmp/recording.m4a",
  language="it"
)

平台说明

Linux

无需额外步骤。确保 uv 位于 PATH 中。

macOS

• 如果安装后找不到 uv：export PATH="$HOME/.local/bin:$PATH"

Windows（WSL）

Claude Code 在 WSL 内运行。所有路径都必须使用 Linux 格式：

• 令牌路径：/home/USER/tools/...（而非 /mnt/c/...）
• 如果找不到 uv：运行 source ~/.bashrc，或将 ~/.local/bin 添加到 PATH

故障排除

问题	解决方案
GROQ_API_KEY not set	将其添加到 MCP 配置的 env 部分
Google Chat token not found	设置 GCHAT_TOKEN_PATH，或对 Google Chat MCP 进行身份验证
Groq API error 413	音频文件过大（Groq 限制：25MB）
uv: command not found	安装 uv（见前提条件）

工作原理

Claude Code → MCP tool call → server.py
  1. Parse Google Chat URL
  2. Fetch message via Google Chat API (OAuth2 token)
  3. Download audio attachment via media API
  4. Send to Groq Whisper API (whisper-large-v3)
  5. Return transcribed text

许可证

MIT