mcp-listen

mcp-listen

AI エージェントに音声を聞き取る機能を提供します

MCP 対応エージェント向けの、マイク音声の取り込みと音声テキスト変換ツールです。

ツール

ツール	説明
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 で取得した 0 以上の整数インデックス、または空でない文字列 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	システムのデフォルト	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	話者が話すのをやめたときに録音を停止します。duration_ms の時間ちょうど録音するには、false を指定してください
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.	LLM のシステムプロンプト

応答例：

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

結果の種類。 voice_query は5種類の結果を返します。構造化フィールドが契約です（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."
}

文字起こしの失敗や依存関係のエラーが発生した場合は、実際の原因（モデルが見つからない、whisper の読み込みに失敗、Ollama が起動していない、タイムアウト、モデルの応答が空など）とともに isError: true が返されます。これにより、呼び出し元はキャプチャ、文字起こし、言語モデルのどの段階で失敗したのかを調査できます。

動作の仕組み

mcp-listen は、クロスプラットフォームのマイクキャプチャに decibri を使用します。ffmpeg、SoX、システムのオーディオツールは不要です。セットアップ不要のネイティブバイナリがあらかじめ用意されています。

音声は、音声認識エンジンの標準形式である 16kHz モノラルの 16 ビット PCM としてキャプチャされます。

無音による停止には、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：「マイクを開けません」 Windows では、既定でマイクへのアクセスがブロックされている場合があります。設定 > プライバシーとセキュリティ > マイクを開き、デスクトップアプリのマイクへのアクセスが有効になっていることを確認してください。

Ollama：「Ollama が実行されていません」 Ollama のインストールによっては、バックグラウンドサービスとして自動的に起動します。このエラーが表示された場合は、ollama serve を手動で実行するか、Ollama サービスが実行中か確認してください。

Whisper：「モデルが見つかりません」 初回使用前に Whisper モデルファイルをダウンロードする必要があります。手順については、Whisper モデルのセットアップを参照してください。

Whisper：「インストール済みですが、読み込みに失敗しました」 @kutalia/whisper-node-addon パッケージは存在しますが、依存するネイティブライブラリがシステムに存在しないか、互換性がありません。エラーには、該当するライブラリ名を含むローダーのメッセージが表示されます。パッケージを再インストールしても解決しません。該当するライブラリの問題を解決してください。

ライセンス

Apache-2.0。詳細は LICENSE を参照してください。

Copyright 2026 Decibri