mcp-listen

<!-- markdownlint-disable MD033 MD041 -->

<p align="center">
  <a href="https://decibri.com">
    <img
      src="https://github.com/user-attachments/assets/62a4c561-da48-401d-9142-220854566330"
      alt="Decibri mcp-listen"
      width="100%">
  </a>
</p>

# mcp-listen

**Give your AI agents the ability to listen**

Microphone capture and speech-to-text tools for MCP-compatible agents.
        
<div>
  <!-- badges: start -->
  <table>
    <tr>
      <td><strong>Meta</strong></td>
      <td>
        <a href="https://github.com/decibri/mcp-listen"><img src="https://badge.mcpx.dev?type=server" title="MCP Server" alt="MCP Server" /></a>&nbsp;
        <a href="https://www.npmjs.com/package/mcp-listen"><img src="https://img.shields.io/npm/v/mcp-listen" alt="npm version"></a>&nbsp;
        <a href="https://github.com/decibri/mcp-listen/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="Apache 2.0 License"></a>&nbsp;
        <a href="https://github.com/decibri/mcp-listen/actions/workflows/ci.yml"><img src="https://github.com/decibri/mcp-listen/actions/workflows/ci.yml/badge.svg" alt="CI"></a>&nbsp;
        <a href="https://glama.ai/mcp/servers/decibri/mcp-listen"><img src="https://glama.ai/mcp/servers/decibri/mcp-listen/badges/score.svg" alt="mcp-listen MCP server" /></a>&nbsp;
      </td>
    </tr>
  </table>
  <!-- badges: end -->
</div>

## Tools

| Tool | Description |
| ------ | ------------- |
| `list_audio_devices` | List available microphone input devices |
| `capture_audio` | Record audio from the microphone and save as WAV |
| `voice_query` | Capture, transcribe on this machine (whisper.cpp), and query a model through the local Ollama daemon |

## Quick Start

### Claude Code

```bash
claude mcp add mcp-listen npx mcp-listen
```

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

Add to your MCP configuration:

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

Compatible with Claude Desktop, ChatGPT Desktop, Cursor, GitHub Copilot, Windsurf, VS Code, Gemini, Zed, and any MCP-compatible client.

### Global Install

```bash
npm install -g mcp-listen
```

## Requirements

**Supported platforms:**

- Windows x64
- macOS Apple silicon (arm64)
- Linux x64 and arm64 (glibc)

Intel Mac (darwin-x64) is not supported: Apple has discontinued the platform and no decibri binary is published for it.

**For `list_audio_devices` and `capture_audio`:**

- Node.js 18+
- A microphone

**For `voice_query` (optional):**

- [Ollama](https://ollama.com) running locally
- Whisper GGML model (see [Whisper Model Setup](#whisper-model-setup))

## Tool Reference

Arguments are validated before anything is recorded or written. An argument a tool does not declare is rejected with an error naming it, rather than silently ignored. `duration_ms` must be an integer between 100 and 30000; `silence_ms` an integer between 100 and 10000; `stop_on_silence` a boolean; `device` a non-negative integer index or a non-empty string id from `list_audio_devices`. A `silence_ms` that cannot take effect (passed without silence-stopping active) is rejected for the same reason unknown arguments are. A rejected call writes nothing to disk.

### list_audio_devices

Returns a JSON array of available audio input devices.

**Parameters:** None

**Example response:**

```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 }
]
```

The `id` is stable across reboots and device changes. The `index` is positional and can shift when devices are added or removed, and names are not unique. Prefer `id` when selecting a device. In the rare case the host cannot produce a stable id for a device, its `id` is an empty string and it can only be selected by `index`.

### capture_audio

Records audio from the microphone and saves as a WAV file. Records for exactly `duration_ms` by default, or until the speaker stops talking with `stop_on_silence: true`.

**Parameters:**

| Parameter | Type | Default | Description |
| ---------- | ------ | --------- | ------------- |
| `duration_ms` | number | 5000 | Recording duration in milliseconds (100-30000). A maximum, not an exact length, when `stop_on_silence` is true |
| `device` | number or string | system default | Device index or stable device `id` from `list_audio_devices` |
| `stop_on_silence` | boolean | false | Stop when the speaker stops talking, detected with on-device voice activity detection (Silero VAD, bundled, no download) |
| `silence_ms` | number | 1000 | Continuous silence in milliseconds that ends a `stop_on_silence` recording (100-10000). Requires `stop_on_silence: true` |

**Example response (fixed duration):**

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

**Example response (`stop_on_silence: true`):**

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

With `stop_on_silence`, `duration_ms` in the response is the actual captured length, and `stopped_by` says how the recording ended: `"silence"` (the speaker finished), `"ceiling"` (the `duration_ms` maximum was reached), or `"no_speech_timeout"` (nobody spoke for 10 seconds; the WAV is still returned, with `speech_detected: false`, so silence is a reported outcome rather than an error). Detection runs per ~100ms audio buffer, so the effective hangover rounds up to the next buffer, and the recording keeps everything from the start of the call through the stop decision: nothing is gated or clipped at speech boundaries, and the audio itself is byte-identical to a fixed-duration capture of the same sounds.

### voice_query

Full voice pipeline: capture audio, transcribe it on this machine with whisper.cpp, send the transcription to the local Ollama daemon, and return the transcription and the response. The audio stays on this machine. Recording stops automatically when the speaker stops talking; pass `stop_on_silence: false` for a fixed-length recording.

**Parameters:**

| Parameter | Type | Default | Description |
| ----------- | ------ | --------- | ------------- |
| `duration_ms` | number | 15000 / 5000 | Maximum recording duration in milliseconds (100-30000). Default 15000 while silence-stopping is active, 5000 with `stop_on_silence: false` |
| `device` | number or string | system default | Device index or stable device `id` from `list_audio_devices` |
| `stop_on_silence` | boolean | true | Stop recording when the speaker stops talking. Pass false to record for exactly `duration_ms` |
| `silence_ms` | number | 1000 | Continuous silence in milliseconds that ends the recording (100-10000) |
| `whisper_model` | string | ggml-base.en.bin | Path or filename of Whisper GGML model |
| `language` | string | en | Language code for transcription |
| `model` | string | llama3.2 | Ollama model name |
| `prompt` | string | You are a helpful assistant. | System prompt for the LLM |

**Example response:**

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

**Result outcomes.** `voice_query` reports five distinct outcomes. The **structured fields are the contract** (`isError`, `speech_detected`, `transcription`); any `message` is a human-readable hint whose wording is not part of the contract, so a caller branches on the fields, never on the prose. The rule is simple: **if the pipeline ran, the result is a success (even when it found no words); if a dependency broke, the result is an error.**

| Outcome | `isError` | `speech_detected` | `transcription` | `response` |
| --- | --- | --- | --- | --- |
| Normal | absent | absent | the text | the answer |
| No speech at all | absent | `false` | `null` | `null` |
| Speech, but no transcribable words | absent | `true` (absent with `stop_on_silence: false`) | `null` | `null` |
| Transcription step failed | `true` | absent | absent | absent |
| Ollama unavailable, errored, or empty | `true` | absent | absent (the text if the reply is empty) | absent (`null` if the reply is empty) |

A caller distinguishes "the user was silent" from "the user spoke but produced no words" by `speech_detected` (`false` vs `true`), both carrying `transcription: null`. Non-speech audio never reaches the language model: whisper's non-speech markers (`[BLANK_AUDIO]`, `[MUSIC]`, `(silence)`, and similar) are treated as no usable words rather than sent on as a query.

**No speech** (`speech_detected: false`):

```json
{
  "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, but no transcribable words** (`speech_detected: true`, `transcription: null`):

```json
{
  "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."
}
```

Transcription and dependency failures return `isError: true` with the real cause (a missing model, a whisper load failure, Ollama not running, a timeout, or an empty model response), so a caller debugging can tell whether the failure was in capture, transcription, or the language model.

## How It Works

mcp-listen uses [decibri](h