Skip to main content
Glama
whisper-mcp
by skroes

whisper-mcp

MCP server that exposes a single transcribe_audio tool for Claude Code to transcribe audio files via OpenAI Whisper.

Built to close the "Channels gap" — the official Claude Code Channels plugins (Telegram, Discord, iMessage) deliver voice messages as '(voice message)' + attachment_file_id without transcription. Claude can download the audio via download_attachment and then call this tool to get text.

Tool

transcribe_audio(file_path: str) -> str

Transcribes an audio file (.ogg, .mp3, .m4a, .mp4, .wav, .flac) to text. Uses OpenAI's gpt-4o-mini-transcribe model with language="nl" by default.

Raises:

  • FileNotFoundError — path doesn't exist

  • ValueError — file >25 MB (Whisper API limit)

  • RuntimeError — API error or missing OPENAI_API_KEY

Related MCP server: whisper-windows-mcp

Install

Production

uv tool install git+https://github.com/skroes/whisper-mcp.git

Development

git clone https://github.com/skroes/whisper-mcp.git
cd whisper-mcp
python -m venv .venv
.venv/bin/pip install -e ".[dev]"

Register with Claude Code

claude mcp add \
  --scope user \
  --env OPENAI_API_KEY="$(op read 'op://Tooling Hub en integraties/.../api_key')" \
  whisper \
  -- "$HOME/.local/bin/whisper-mcp"

# Verify
claude mcp list
claude mcp get whisper

For development (venv install):

claude mcp add \
  --scope user \
  --env OPENAI_API_KEY="$(op read ...)" \
  whisper \
  -- "$HOME/wd-workspace/repo/whisper-mcp/.venv/bin/python" -m whisper_mcp

Claude prompt instruction

Add to ~/.claude/CLAUDE.md:

## Voice attachments in Channels

When a channel message contains a voice/audio attachment (detect via
`attachment_file_id` in the channel tag or `(voice message)` placeholder):

1. Use the channel's attachment download tool (e.g. `download_attachment`
   for Telegram) to save the file locally.
2. Call `transcribe_audio(path)` from the whisper MCP server.
3. Treat the returned transcript as the user's actual message.
4. Continue working in the current session context.
5. If transcription fails, report the error and ask the user to retry
   or type the message.

Testing locally

# Standalone Python call
.venv/bin/python -c "
import asyncio
from whisper_mcp.transcribe import transcribe_audio
print(asyncio.run(transcribe_audio('/path/to/test.ogg')))
"

# MCP dev mode (interactive)
.venv/bin/mcp dev whisper_mcp/__main__.py

Limits

  • File size: 25 MB (OpenAI Whisper API limit). Larger files raise ValueError — split required (post-MVP feature).

  • Language: hardcoded nl. Multi-language is post-MVP.

License

MIT

Available Tools

1 tool
transcribe_audioA

Transcribe an audio file to text via OpenAI Whisper.

Use this after download_attachment on a channel voice/audio attachment to get the user's actual spoken message as text.

Args: file_path: Absolute or relative path to the audio file (e.g. /home/.../STATE_DIR/inbox/voice-123.ogg). Supported formats: .ogg .mp3 .m4a .mp4 .wav .webm .flac.

Returns: Transcribed text. May be empty for silent audio.

Errors are returned as MCP isError responses with the exception type and message (FileNotFoundError, ValueError for >25 MB, or RuntimeError for API/config failures).

Inputs: file_path (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.8/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only one tool exists, so there is no ambiguity. The agent will always select the correct tool.

    Naming Consistency5/5

    With a single tool named 'transcribe_audio', the naming is trivially consistent and follows a clear verb_noun pattern.

    Tool Count4/5

    One tool is appropriate for a single-purpose transcription server, though the typical range for well-scoped servers is 3-15 tools. It is slightly below that range but not unreasonable.

    Completeness5/5

    The server's sole purpose is audio transcription, and the tool fully covers that operation with support for various formats and error handling. No additional capabilities are necessary.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers