whisper-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@whisper-mcp transcribe the voice message attachment I just downloaded"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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) -> strTranscribes 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 existValueError— file >25 MB (Whisper API limit)RuntimeError— API error or missingOPENAI_API_KEY
Related MCP server: whisper-windows-mcp
Install
Production
uv tool install git+https://github.com/skroes/whisper-mcp.gitDevelopment
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 whisperFor 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_mcpClaude 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__.pyLimits
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 tooltranscribe_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
Scored across 1 tool
Only one tool exists, so there is no ambiguity. The agent will always select the correct tool.
With a single tool named 'transcribe_audio', the naming is trivially consistent and follows a clear verb_noun pattern.
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.
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
Related MCP Connectors
MCP server for RiverScript, an AI transcription platform - fetches transcripts shared via a link.
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Transcribe audio and video with Speechmatics speech-to-text from Claude and any MCP client.
The Listenetic MCP server is a remote, cloud-hosted server that enables AI assistants like ChatGPT and Claude to convert articles, documents, websites, and videos into high-quality AI-generated audio. It provides multi-format support for text and binary files, natural-sounding text-to-audio conversion using AI, and specialized processing for SSML, markup, markdown, and various media formats through three core tools: listentic_supported_mimetypes, listentic_add_content_text, and listentic_add_content_binary.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that enables transcribing local audio files and Telegram voice messages using OpenAI's Whisper via local inference or cloud API. It supports multiple audio formats, automatic language detection, and optional word-level timestamps for AI-powered audio analysis.51MIT
- FlicenseAqualityBmaintenanceA Windows-native MCP server that lets Claude Desktop transcribe audio files locally using whisper.cpp, with no internet connection required.13114 npm2-
- AlicenseAqualityDmaintenanceMCP server that brings ElevenLabs to Claude Code — text-to-speech, sound effects, music generation, voice cloning, speech-to-speech, transcription, and voice isolation. 8 tools for industry-leading AI audio.8MIT
- AlicenseAqualityBmaintenanceMCP server for audio transcription using local faster-whisper or OpenAI Whisper API, enabling multilingual transcription with optional GPT post-processing.3160 PyPIMIT