Skip to main content
Glama
skroes

whisper-mcp

by skroes
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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-telegram-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).

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavior: uses OpenAI Whisper, returns text (possibly empty), and details specific error types (FileNotFoundError, ValueError for >25 MB, RuntimeError for API/config). No contradictory statements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Structured into clear sections (purpose, usage, args, returns, errors), front-loaded with key information, and no redundant text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with no annotations, the description covers all necessary information: purpose, prerequisites, input format, output, and error handling. Complete with respect to context signals.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description compensates by explaining the 'file_path' parameter with example path and supported formats, adding meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Transcribe an audio file to text via OpenAI Whisper,' specifying the verb and resource, and distinguishes itself effectively in the absence of siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit context to use after 'download_attachment' and lists supported formats, but does not discuss when not to use or alternative tools. Acceptable given no siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.8/5.0
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

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/skroes/whisper-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server