mcp-listen

mcp-listen

让你的 AI Agent 能够倾听

为兼容 MCP 的 Agent 提供麦克风采集和语音转文本工具。

工具

工具	说明
list_audio_devices	列出可用的麦克风输入设备
capture_audio	录制麦克风音频并保存为 WAV
voice_query	采集音频，在本机使用 whisper.cpp 转录，并通过本地 Ollama 守护进程向模型发起查询

快速开始

Claude Code

claude mcp add mcp-listen npx mcp-listen

Claude Desktop / ChatGPT Desktop / Cursor / Windsurf / VS Code

添加到你的 MCP 配置中：

{
  "mcpServers": {
    "mcp-listen": {
      "command": "npx",
      "args": ["-y", "mcp-listen"]
    }
  }
}

兼容 Claude Desktop、ChatGPT Desktop、Cursor、GitHub Copilot、Windsurf、VS Code、Gemini、Zed 以及任何兼容 MCP 的客户端。

全局安装

npm install -g mcp-listen

要求

支持的平台：

• Windows x64
• macOS Apple silicon（arm64）
• Linux x64 和 arm64（glibc）

不支持 Intel Mac（darwin-x64）：Apple 已停止支持该平台，且未发布适用于该平台的 decibri 二进制文件。

使用 list_audio_devices 和 capture_audio 的要求：

• Node.js 18+
• 麦克风

使用 voice_query 的要求（可选）：

• 本机运行的 Ollama
• Whisper GGML 模型（参见Whisper 模型设置）

工具参考

执行录制或写入操作之前会先验证参数。工具未声明的参数会被拒绝，并显示指出该参数的错误，而不是被静默忽略。duration_ms 必须是介于 100 和 30000 之间的整数；silence_ms 必须是介于 100 和 10000 之间的整数；stop_on_silence 必须是布尔值；device 必须是非负整数索引，或来自 list_audio_devices 的非空字符串 ID。如果未启用静音停止却传入了 silence_ms，该参数将无法生效，因此也会像未知参数一样被拒绝。被拒绝的调用不会向磁盘写入任何内容。

list_audio_devices

返回可用音频输入设备的 JSON 数组。

**参数：**无

响应示例：

[
  { "index": 0, "name": "Microphone", "id": "wasapi:{0.0.1.00000000}.{00000000-0000-0000-0000-000000000001}", "maxInputChannels": 2, "defaultSampleRate": 48000, "isDefault": true },
  { "index": 1, "name": "Microphone Array", "id": "wasapi:{0.0.1.00000000}.{00000000-0000-0000-0000-000000000002}", "maxInputChannels": 2, "defaultSampleRate": 48000, "isDefault": false }
]

id 在重启和设备变更后保持稳定。index 表示位置，添加或移除设备时可能发生变化，而且设备名称并不唯一。选择设备时优先使用 id。在极少数情况下，主机无法为设备生成稳定的 ID，此时其 id 为空字符串，只能通过 index 选择。

capture_audio

从麦克风录制音频并保存为 WAV 文件。默认情况下，录制时长恰好为 duration_ms 指定的时长；如果设置了 stop_on_silence: true，则录制会在说话者停止说话时结束。

参数：

参数	类型	默认值	描述
duration_ms	number	5000	录制时长，单位为毫秒（100-30000）。当 stop_on_silence 为 true 时，此值为最长时长，而非精确时长
device	number or string	system default	来自 list_audio_devices 的设备索引或稳定设备 id
stop_on_silence	boolean	false	使用设备端语音活动检测（Silero VAD，随附，无需下载）检测到说话者停止说话时停止录制
silence_ms	number	1000	结束 stop_on_silence 录制所需的连续静音时长，单位为毫秒（100-10000）。需要设置 stop_on_silence: true

示例响应（固定时长）：

{
  "path": "/tmp/mcp-listen-1712345678901.wav",
  "duration_ms": 5000,
  "sample_rate": 16000,
  "channels": 1,
  "size_bytes": 160044
}

示例响应（stop_on_silence: true）：

{
  "path": "/tmp/mcp-listen-1712345678901.wav",
  "duration_ms": 2600,
  "sample_rate": 16000,
  "channels": 1,
  "size_bytes": 83244,
  "stopped_by": "silence",
  "speech_detected": true
}

使用 stop_on_silence 时，响应中的 duration_ms 表示实际录制时长，stopped_by 表示录制结束的原因："silence"（说话者说完了）、"ceiling"（达到 duration_ms 上限），或 "no_speech_timeout"（10 秒内无人说话；仍会返回 WAV，并将 speech_detected 设为 false，因此静音会作为一种结果报告，而非错误）。检测按每个约 100ms 的音频缓冲区运行，因此实际静音等待时长会向上取整到下一个缓冲区；录音会保留从调用开始到决定停止期间的所有内容：语音边界处不会进行门控或裁剪，音频本身与对相同声音进行固定时长录制所得的音频逐字节一致。

voice_query

完整语音流水线：采集音频，在本机使用 whisper.cpp 转录，将转录文本发送到本地 Ollama 守护进程，并返回转录文本和回复。音频始终保留在本机。说话者停止说话时，录音会自动停止；设置 stop_on_silence: false 可录制固定时长。

参数：

参数	类型	默认值	描述
duration_ms	number	15000 / 5000	最大录音时长，单位为毫秒（100-30000）。静音停止功能启用时默认为 15000；设置 stop_on_silence: false 时默认为 5000
device	number or string	system default	list_audio_devices 返回的设备索引或稳定设备 id
stop_on_silence	boolean	true	说话者停止说话时停止录音。传入 false 可录制恰好 duration_ms 时长
silence_ms	number	1000	结束录音所需的连续静音时长，单位为毫秒（100-10000）
whisper_model	string	ggml-base.en.bin	Whisper GGML 模型的路径或文件名
language	string	en	转录所用的语言代码
model	string	llama3.2	Ollama 模型名称
prompt	string	You are a helpful assistant.	大模型的系统提示词

响应示例：

{
  "transcription": "What is the default port for PostgreSQL?",
  "response": "PostgreSQL runs on port 5432 by default.",
  "model": "llama3.2"
}

结果类型。 voice_query 会报告五种不同的结果。结构化字段是接口契约（isError、speech_detected、transcription）；任何 message 都只是便于人理解的提示，其措辞不属于接口契约，因此调用方应根据字段进行分支判断，而不是根据文本描述。规则很简单：如果流水线运行成功，结果就是成功（即使没有识别出任何词语）；如果依赖项出错，结果就是错误。

结果	isError	speech_detected	transcription	response
正常	不存在	不存在	文本	回复
完全没有语音	不存在	false	null	null
有语音，但没有可转录的词语	不存在	true（设置 stop_on_silence: false 时不存在）	null	null
转录步骤失败	true	不存在	不存在	不存在
Ollama 不可用、出错或返回内容为空	true	不存在	不存在（回复为空时为文本）	不存在（回复为空时为 null）

调用方可通过 speech_detected（false 与 true）区分“用户没有说话”和“用户说话了，但没有识别出任何词语”；这两种情况的 transcription 均为 null。非语音音频不会发送到大模型：whisper 的非语音标记（[BLANK_AUDIO]、[MUSIC]、(silence) 等）会被视为没有可用词语，而不会作为查询发送。

没有语音（speech_detected: false）：

{
  "speech_detected": false,
  "stopped_by": "no_speech_timeout",
  "transcription": null,
  "response": null,
  "message": "No speech was detected. Ask the user to repeat, or check that the correct microphone is selected."
}

有语音，但没有可转录的词语（speech_detected: true、transcription: null）：

{
  "speech_detected": true,
  "stopped_by": "silence",
  "transcription": null,
  "response": null,
  "message": "Speech was detected but could not be transcribed. It may have been too quiet, too brief, or unclear. Ask the user to repeat, a little louder and closer to the microphone."
}

转录失败和依赖项故障会返回 isError: true，并附上实际原因（模型缺失、whisper 加载失败、Ollama 未运行、超时或模型响应为空），以便调用方调试时判断故障发生在采集、转录还是大模型环节。

工作原理

mcp-listen 使用 decibri 跨平台采集麦克风音频。无需 ffmpeg、SoX 或系统音频工具。预构建的原生二进制文件，无需任何设置。

音频以 16-bit PCM、16kHz 单声道格式采集，这是语音转文本引擎的标准格式。

静音停止功能使用 decibri 内置的 Silero 语音活动检测模型，通过捆绑的 ONNX Runtime 在设备本地运行。不会下载任何额外内容，也不会有音频离开本机。停止判断依据是已采集的音频，而非实际经过的时间；VAD 只负责判断何时停止，不会门控或修改录制的样本。

voice_query 工具会采集音频，并在本机使用 whisper.cpp 转录，然后将转录内容发送到本地 Ollama 守护进程，并将转录内容和回复返回给调用客户端。音频会保留在本机。

Whisper 模型设置

voice_query 工具需要一个 Whisper GGML 模型文件。下载一个：

Linux / macOS：

mkdir -p ~/.mcp-listen/models
curl -L -o ~/.mcp-listen/models/ggml-base.en.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin

Windows (PowerShell)：

mkdir "$env:USERPROFILE\.mcp-listen\models" -Force
Invoke-WebRequest -Uri "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin" -OutFile "$env:USERPROFILE\.mcp-listen\models\ggml-base.en.bin"

模型大小约为 150MB，只需下载一次。你也可以将 WHISPER_MODEL_PATH 环境变量设置为自定义目录。

Ollama 设置

1. 从 https://ollama.com 安装 Ollama
2. 拉取模型：ollama pull llama3.2
3. 确保 Ollama 正在运行：ollama serve

已知限制

1. 突发的响声可能会被识别为语音。 静音停止功能根据 VAD 分数判断“语音已开始”，因此关门声或咳嗽声可能会启动倒计时，并在静音达到 silence_ms 后结束录音，导致录制的内容很短且大多是静音。结果会明确显示这一情况：结果会报告实际时长，voice_query 会返回空转录内容，而不会凭空编造。增加最短语音时长保护是一个可考虑的改进方向。
2. voice_query 要求 Ollama 正在运行。 如果 Ollama 未运行，工具会返回清晰的错误消息。
3. 首次使用前必须下载 Whisper 模型。 voice_query 不会自行下载模型；首次调用前需要预先下载模型（约 150MB）。请参阅 Whisper 模型设置。
4. 不支持流式处理。 MCP 的请求/响应模式意味着必须先采集完整段录音，再进行转录，然后发送给 LLM。没有实时的部分结果。
5. 临时文件。 capture_audio 会将 WAV 文件写入系统临时目录并返回路径，因此调用者读取文件前，该文件必须保持存在。超过 24 小时的录音会在服务下次启动时删除；自上次重启以来录制的文件会一直保留到那时。voice_query 会在查询完成后立即删除录音。

故障排除

Windows：“Error opening microphone” Windows 可能默认禁止访问麦克风。前往 设置 > 隐私和安全性 > 麦克风，确保已为桌面应用启用麦克风访问权限。

Ollama：“Ollama is not running” 某些 Ollama 安装会自动作为后台服务启动。如果看到此错误，请手动运行 ollama serve，或检查 Ollama 服务是否正在运行。

Whisper：“model not found” 首次使用前必须下载 whisper 模型文件。请参阅 Whisper 模型设置了解说明。

Whisper：“installed but failed to load” @kutalia/whisper-node-addon 包已存在，但它依赖的原生库在你的系统上缺失或不兼容。错误中会包含指出相关库的底层加载器消息。重新安装该包无济于事；请解决所提示的库问题。

许可证

Apache-2.0。详情请参阅 LICENSE。

版权所有 2026 Decibri