whisper-transcribe-mcp
This MCP server transcribes audio to text using either a local faster-whisper model or the OpenAI Whisper API, with optional GPT-powered post-processing.
Transcribe audio files (transcribe_file): Convert audio files (mp3, wav, m4a, ogg, flac, webm, etc.) to text by providing an absolute file path.
Transcribe base64-encoded audio (transcribe_base64): Accept audio as a base64-encoded string for programmatic integrations.
Both transcription tools support:
Optional language specification (e.g.,
en,es) or auto-detectionChoice of local model size (
tiny,base,small,medium,large-v3)Optional GPT-4.1 post-processing to fix spelling, grammar, and punctuation
Custom post-processing prompts for domain-specific terminology or proper nouns
List models and configuration (list_models): View the active backend, available local model sizes, and the GPT model used for post-processing.
Backend options:
Local (faster-whisper): Free, works fully offline after model download
OpenAI Whisper API: Cloud-based, requires an API key
Both: OpenAI is prioritized when an API key is present, with automatic fallback to local if the API call fails
Compatible with Claude Desktop and Claude Code on macOS, Windows, and Linux.
Provides audio transcription using OpenAI's Whisper API, requiring an API key and internet connection.
Click on "Install 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-transcribe-mcptranscribe the file meeting.mp3"
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-transcribe-mcp
MCP server for audio transcription using faster-whisper (local, free, offline) or OpenAI Whisper API (cloud, requires API key). Works with Claude Desktop and Claude Code on macOS, Windows, and Linux.
Prerequisites
macOS
Option A — uv (recommended):
brew install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | shOption B — Python:
Python 3.10+ is included in macOS 12.3+. You can also install it with brew install python.
Windows
Option A — uv (recommended):
winget install astral-sh.uvOr download the installer from astral.sh/uv.
Option B — Python: Download Python 3.10+ from python.org. During installation, check "Add Python to PATH".
No need to install ffmpeg or any compiler — everything is bundled in the package.
Linux
Option A — uv (recommended):
curl -LsSf https://astral.sh/uv/install.sh | shOption B — Python:
# Debian/Ubuntu
sudo apt install python3.12 python3.12-venv
# Fedora
sudo dnf install python3.12
# Arch
sudo pacman -S pythonNo additional system dependencies required.
Related MCP server: audio-transcription-mcp
Installation
Option A — uvx (recommended, no permanent install)
uvx automatically downloads and installs the package in an isolated environment. Only requires uv to be installed.
# Local backend:
uvx "whisper-transcribe-mcp[local]"
# OpenAI backend:
uvx "whisper-transcribe-mcp[openai]"
# Both backends:
uvx "whisper-transcribe-mcp[all]"Option B — pip
# Local backend:
pip install "whisper-transcribe-mcp[local]"
# OpenAI backend:
pip install "whisper-transcribe-mcp[openai]"
# Both backends:
pip install "whisper-transcribe-mcp[all]"Use Cases
Case 1 — Local backend only (free, works offline)
Uses faster-whisper to transcribe locally. The model is downloaded from HuggingFace on first use (~74MB for base) and cached.
Install:
pip install "whisper-transcribe-mcp[local]"Environment variables:
WHISPER_MODEL=base # or tiny, small, medium, large-v3Case 2 — OpenAI backend only (best accuracy, requires API key)
Uses OpenAI's whisper-1 model. Requires an API key and internet connection. No local model downloads.
Install:
pip install "whisper-transcribe-mcp[openai]"Environment variables:
OPENAI_API_KEY=sk-...Case 3 — Both backends (OpenAI if key present, local as fallback)
If OPENAI_API_KEY is set, OpenAI is used automatically. Otherwise falls back to local faster-whisper.
Install:
pip install "whisper-transcribe-mcp[all]"Configuration
Claude Desktop
Config file location by operating system:
OS | Path |
macOS |
|
Windows |
|
Linux |
|
Add the entry inside "mcpServers":
Windows note: Claude Desktop runs in a restricted environment and may not have
uvxin its PATH, and it may use a Python version (e.g. 3.14) for whichctranslate2(a dependency offaster-whisper) does not yet have prebuilt wheels. Two fixes are required:
Use the full path to
uvx.exeinstead of justuvx. Runwhere.exe uvxin PowerShell to find it (usuallyC:\Users\<YourUser>\.local\bin\uvx.exe).Force Python 3.12 via the
--python 3.12flag so that a compatible wheel is used.
Case 1 — Local:
macOS / Linux:
{
"mcpServers": {
"whisper-transcribe": {
"command": "uvx",
"args": ["whisper-transcribe-mcp[local]"],
"env": {
"WHISPER_MODEL": "base"
}
}
}
}Windows:
{
"mcpServers": {
"whisper-transcribe": {
"command": "C:\\Users\\<YourUser>\\.local\\bin\\uvx.exe",
"args": ["--python", "3.12", "whisper-transcribe-mcp[local]"],
"env": {
"WHISPER_MODEL": "base"
}
}
}
}Case 2 — OpenAI:
macOS / Linux:
{
"mcpServers": {
"whisper-transcribe": {
"command": "uvx",
"args": ["whisper-transcribe-mcp[openai]"],
"env": {
"OPENAI_API_KEY": "sk-..."
}
}
}
}Windows:
{
"mcpServers": {
"whisper-transcribe": {
"command": "C:\\Users\\<YourUser>\\.local\\bin\\uvx.exe",
"args": ["--python", "3.12", "whisper-transcribe-mcp[openai]"],
"env": {
"OPENAI_API_KEY": "sk-..."
}
}
}
}Case 3 — Both (OpenAI takes priority if key is set):
macOS / Linux:
{
"mcpServers": {
"whisper-transcribe": {
"command": "uvx",
"args": ["whisper-transcribe-mcp[all]"],
"env": {
"OPENAI_API_KEY": "sk-...",
"WHISPER_MODEL": "base"
}
}
}
}Windows:
{
"mcpServers": {
"whisper-transcribe": {
"command": "C:\\Users\\<YourUser>\\.local\\bin\\uvx.exe",
"args": ["--python", "3.12", "whisper-transcribe-mcp[all]"],
"env": {
"OPENAI_API_KEY": "sk-...",
"WHISPER_MODEL": "base"
}
}
}
}Restart Claude Desktop after editing the file.
Claude Code
Works the same on macOS, Windows, and Linux. Requires uv installed.
Claude Code config file location:
OS | Global | Per project |
macOS / Linux |
|
|
Windows |
|
|
The easiest way to add the server is via the Claude Code CLI, which updates the config file automatically:
# Case 1 — Local:
claude mcp add whisper-transcribe uvx -- "whisper-transcribe-mcp[local]"
# Case 2 — OpenAI:
claude mcp add whisper-transcribe uvx --env OPENAI_API_KEY=sk-... -- "whisper-transcribe-mcp[openai]"
# Case 3 — Both (OpenAI with local fallback):
claude mcp add whisper-transcribe uvx --env OPENAI_API_KEY=sk-... --env WHISPER_MODEL=base -- "whisper-transcribe-mcp[all]"Windows +
[all]: Add--python 3.12before the package name to avoidctranslate2wheel issues. Edit~/.claude.jsondirectly and use"args": ["--python", "3.12", "whisper-transcribe-mcp[all]"].
To add it globally (available in all projects), use --scope user:
claude mcp add --scope user whisper-transcribe uvx -- "whisper-transcribe-mcp[local]"Or edit ~/.claude.json directly and add inside "mcpServers":
{
"mcpServers": {
"whisper-transcribe": {
"command": "uvx",
"args": ["whisper-transcribe-mcp[local]"],
"env": {
"WHISPER_MODEL": "base"
}
}
}
}Environment Variables
Variable | Default | Description |
|
| Local model size: |
| — | If set, activates the OpenAI backend instead of local |
Backend selection and fallback ([all] only)
When installed with [all], the backend is chosen at startup:
OPENAI_API_KEYset → OpenAI is used. If the API call fails at runtime (network error, invalid key, quota exceeded), the server automatically falls back to localfaster-whisperand includes a"fallback_reason"field in the response.OPENAI_API_KEYnot set → localfaster-whisperis used directly, no fallback attempted.
Available Tools
transcribe_file
Transcribes an audio file by path (mp3, wav, m4a, ogg, flac, webm, etc.).
Parameters:
file_path(required): Absolute path to the audio filelanguage(optional): Language code (es,en,fr, etc.). Auto-detected if not provided.model_size(optional): Local model size. Ignored with the OpenAI backend.post_process(optional, defaultfalse): Iftrue, passes the transcription through GPT-4.1 to fix spelling, grammar, and punctuation. Requires theopenaipackage ([openai]or[all]).post_process_prompt(optional): Custom system prompt for GPT post-processing. Use it to provide domain-specific context, proper nouns, or product names that Whisper may have misspelled. Falls back to a generic correction prompt if not provided.
Response (without post-processing):
{
"text": "Full transcription...",
"language": "en",
"language_probability": 0.99,
"segments": [
{ "start": 0.0, "end": 4.2, "text": "First segment..." }
],
"backend": "local",
"model": "base"
}Response (with post_process: true):
{
"text": "Corrected transcription...",
"raw_text": "Original transcription from Whisper...",
"post_process_model": "gpt-4.1",
"language": "en",
"language_probability": 0.99,
"segments": [...],
"backend": "local",
"model": "base"
}If post-processing fails, text retains the original transcription and a post_process_error field is added.
transcribe_base64
Transcribes audio provided as a base64-encoded string. Useful for programmatic integrations.
Parameters:
audio_base64(required): Base64-encoded audio dataextension(optional, defaultmp3): File extension (mp3,wav,ogg, etc.)language(optional): Language codemodel_size(optional): Local model sizepost_process(optional, defaultfalse): Same as intranscribe_file.post_process_prompt(optional): Same as intranscribe_file.
list_models
Shows the active backend configuration, available local models, and the GPT model used for post-processing.
Local Model Sizes
Model | Size | Relative Speed | Notes |
| 39 MB | ~32x | Fastest, least accurate |
| 74 MB | ~16x | Good balance (default) |
| 244 MB | ~6x | Better accuracy |
| 769 MB | ~2x | High accuracy |
| 1.5 GB | ~1x | Best accuracy, slowest |
Models are downloaded automatically from HuggingFace on first use and cached locally.
Troubleshooting
MCP not loading in Claude Desktop on Windows
Symptom: The server fails to start with a dependency resolution error like:
ctranslate2>=4.6.1 has no wheels with a matching platform tag (e.g., `win32`)
hint: You require CPython 3.14 (`cp314`), but we only found wheels for `ctranslate2` with: `cp39`, `cp310`, `cp311`, `cp312`, `cp313`Cause: Two issues combined:
Claude Desktop does not include the user's local
binin its PATH, souvxmust be referenced by full path.Claude Desktop's
uvxmay pick a Python version (e.g. 3.14) for whichctranslate2— a native dependency offaster-whisper— does not yet have prebuilt wheels for Windows.
Fix: Use the full path to uvx.exe and force Python 3.12 explicitly:
"whisper-transcribe": {
"command": "C:\\Users\\<YourUser>\\.local\\bin\\uvx.exe",
"args": ["--python", "3.12", "whisper-transcribe-mcp[local]"],
"env": { "WHISPER_MODEL": "base" }
}To find your exact uvx.exe path, run in PowerShell:
where.exe uvxTranscribing audio files in Claude Desktop
Symptom: Claude Desktop fails to transcribe an uploaded audio file. It may attempt to read the file as base64 and pass it to transcribe_base64, which then fails or hangs for files larger than ~50 KB.
Cause: Claude Desktop runs in a sandboxed Linux container. When you upload a file using the attachment button, it is stored at a path like /mnt/user-data/uploads/audio.mp3 — inside the container. The MCP server runs on your Windows machine and has no access to that container path. Claude's fallback of base64-encoding the file and passing it to transcribe_base64 fails in practice because even a small audio file produces hundreds of kilobytes of base64 text, which overflows the context window before the tool call can be made.
Fix: Do not use the attachment button to upload audio files. Instead, place the file anywhere on your Windows filesystem and reference its path directly in the message:
"Transcribe the file at
C:\Users\YourUser\Downloads\audio.mp3"
The MCP server will read the file directly from Windows and send it to the transcription backend. This works for files of any size within the Whisper API limit (25 MB).
Development
This project uses uv for reproducible development environments:
uv sync --group dev
uv run ruff check .
uv run ruff format --check .
uv run pytest -q
uv run pre-commit installSee CONTRIBUTING.md for the contribution workflow.
Distribution and releases
The package is distributed through PyPI and
described by server.json for the
official MCP Registry. Version tags publish both
destinations through GitHub OIDC, without long-lived publishing tokens. See
docs/publishing.md for the release checklist and one-time repository setup.
The Registry entry describes the base PyPI package. Choose the [local], [openai], or [all]
extra from the installation examples above so the transcription backend you need is installed.
License
MIT — see LICENSE
Available Tools
3 toolslist_modelsA
List available Whisper model sizes and current configuration.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description states it lists information but does not explicitly confirm read-only or side effects. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with zero waste; front-loaded with action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No parameters, output schema exists to describe return values; description fully covers purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema (0 count), baseline is 4. Description adds no param info, but none needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'List' and specific resource 'available Whisper model sizes and current configuration'. Distinguishes from sibling tools transcribe_base64 and transcribe_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage for checking available models, but no explicit when-to-use or alternatives given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
transcribe_base64B
Transcribe audio provided as a base64-encoded string.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Language code. Auto-detected if not provided. | |
| extension | No | File extension for the temp file (mp3, wav, m4a, ogg, etc.). | mp3 |
| model_size | No | Local model size. Ignored when using the OpenAI backend. | |
| audio_base64 | Yes | Base64-encoded audio data. | |
| post_process | No | If True, passes the transcription through GPT to fix spelling, grammar, and punctuation. Requires the openai package. | |
| post_process_prompt | No | Custom system prompt for post-processing. Use this to provide domain-specific context, proper nouns, or product names. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral details such as backend used, internet requirement, output format, or limitations (e.g., audio length), relying solely on minimal description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words, efficiently conveying the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a rich input schema and available output schema, the description omits essential context such as return format, prerequisites, and backend behavior, making it incomplete for complex tool usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds no additional meaning beyond what the input schema already provides; baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool transcribes audio from a base64-encoded string, distinguishing it from siblings like transcribe_file (file-based) and list_models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for base64 audio input but lacks explicit when-to-use, when-not-to-use, or alternative guidance, leaving room for confusion with transcribe_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
transcribe_fileB
Transcribe an audio file to text.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Language code (e.g. 'es', 'en', 'fr'). Auto-detected if not provided. | |
| file_path | Yes | Absolute path to the audio file (mp3, wav, m4a, ogg, flac, etc.) | |
| model_size | No | Local model size: tiny, base, small, medium, large-v3. Ignored when using the OpenAI backend. Defaults to the WHISPER_MODEL environment variable (default: 'base'). | |
| post_process | No | If True, passes the transcription through GPT to fix spelling, grammar, and punctuation. Requires the openai package. | |
| post_process_prompt | No | Custom system prompt for post-processing. Use this to provide domain-specific context, proper nouns, or product names that Whisper may have misspelled. Falls back to a generic correction prompt if not provided. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose any behavioral traits beyond the basic action. It does not mention if the tool requires network access, writes temporary files, uses local or remote processing, or any error conditions. Since no annotations are provided, the description carries the full burden but fails to provide meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is immediately clear. It is appropriately front-loaded but could benefit from minimal structured details (e.g., supported formats) without becoming verbose. The extreme brevity does not hurt clarity but leaves some gaps.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the presence of an output schema and full parameter documentation, the description fails to provide context about when to use this tool vs. the sibling 'transcribe_base64', or about any side effects or limitations. For a tool with five parameters and multiple options, the description is insufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already documents all five parameters thoroughly. The tool description adds no additional semantic value beyond what is in the schema, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('transcribe') and the resource ('audio file'), immediately distinguishing the tool from its siblings 'list_models' (which lists models) and 'transcribe_base64' (which transcribes base64-encoded audio). The verb+resource combination is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus its siblings or alternatives. It does not mention file size limits, audio duration constraints, or any prerequisites. Users receive no contextual advice on selecting this tool over transcribe_base64 or list_models.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
Each tool serves a distinct purpose: listing models, transcribing from base64, and transcribing from file. No overlap in functionality.
All tool names follow a consistent verb_noun pattern using snake_case (list_models, transcribe_base64, transcribe_file).
Three tools is well-scoped for a transcription server: one for configuration/model listing and two for handling different input formats (base64 vs file).
The tool surface covers the core transcription workflow with two input methods and model listing. Minor gap: no support for streaming or URL-based audio input.
Maintenance
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
MCP server for Speech-to-Text
MCP server for RiverScript, an AI transcription platform - fetches transcripts shared via a link.
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server exposing the AceDataCloud Fish Audio API (text-to-speech with voice conditioning)
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
- AlicenseNot gradedqualityDmaintenanceMCP server for audio transcription with speaker diarization. Transcribes MP3/WAV files using Faster-Whisper and pyannote.audio, outputs markdown with speaker labels, timestamps, summaries, and action items.1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for audio transcription using OpenRouter models, supporting verbatim, cleaned, and custom transcription modes.161MIT
- FlicenseAqualityDmaintenanceThis MCP server enables audio transcription using OpenAI Whisper, supporting various model sizes and base64-encoded audio input via stdio or HTTP transport.1-
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/ZahiriNatZuke/whisper-transcribe-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server