whisper-transcribe-mcp
MCP server for audio transcription using (local, free, offline) or (cloud, requires API key). Works with Claude Desktop and Claude Code on macOS, Windows, and Linux.
Agenten stärken
Der eigene Befehl des Herausgebers. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
uvx whisper-transcribe-mcp==1.1.3Claude Code hat keinen Installationslink für einen lokalen Befehl. Kopieren Sie den Befehl unten und führen Sie ihn in einem Terminal aus.
OPENAI_API_KEY=<secret> WHISPER_MODEL=<value> WHISPER_POST_PROCESS_MODEL=<value> claude mcp add io.github.zahirinatzuke-whisper-transcribe-mcp -- uvx whisper-transcribe-mcp==1.1.3In einem Terminal ausführen.
{ "mcpServers": { "io.github.zahirinatzuke-whisper-transcribe-mcp": { "command": "uvx", "args": [ "whisper-transcribe-mcp==1.1.3" ], "env": { "OPENAI_API_KEY": "<secret>", "WHISPER_MODEL": "<value>", "WHISPER_POST_PROCESS_MODEL": "<value>" } } }}claude_desktop_config.json
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenOption A — uv (recommended):
brew install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh
Option B — Python:
Python 3.10+ is included in macOS 12.3+. You can also install it with brew install python.
Option A — uv (recommended):
winget install astral-sh.uv
Or 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.
Option A — uv (recommended):
curl -LsSf https://astral.sh/uv/install.sh | sh
Option B — Python:
# Debian/Ubuntu
sudo apt install python3.12 python3.12-venv
# Fedora
sudo dnf install python3.12
# Arch
sudo pacman -S python
No additional system dependencies required.
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]"
# Local backend:
pip install "whisper-transcribe-mcp[local]"
# OpenAI backend:
pip install "whisper-transcribe-mcp[openai]"
# Both backends:
pip install "whisper-transcribe-mcp[all]"
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-v3
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-...
If OPENAI_API_KEY is set, OpenAI is used automatically. Otherwise falls back to local faster-whisper.
Install:
pip install "whisper-transcribe-mcp[all]"
Config file location by operating system:
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.
Works the same on macOS, Windows, and Linux. Requires uv installed.
Claude Code config file location:
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"
}
}
}
}
[all] only)When installed with [all], the backend is chosen at startup:
OPENAI_API_KEY set → OpenAI is used. If the API call fails at runtime (network error, invalid key, quota exceeded), the server automatically falls back to local faster-whisper and includes a "fallback_reason" field in the response.OPENAI_API_KEY not set → local faster-whisper is used directly, no fallback attempted.The server runs locally over stdio and only needs the access its tools imply:
Tool inputs are validated before use: model_size must be a known Whisper model name,
language must be an ISO 639 code, and extension must be a known audio format. OpenAI errors
are returned as a short summary (error type and HTTP status); the full message goes to stderr.
Releases are published from GitHub Actions with PyPI Trusted Publishing and PEP 740 provenance
attestations.
transcribe_fileTranscribes 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, default false): If true, passes the transcription through GPT-4.1 to fix spelling, grammar, and punctuation. Requires the openai package ([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_base64Transcribes audio provided as a base64-encoded string. Useful for programmatic integrations.
Parameters:
audio_base64 (required): Base64-encoded audio dataextension (optional, default mp3): File extension (mp3, wav, ogg, etc.)language (optional): Language codemodel_size (optional): Local model sizepost_process (optional, default false): Same as in transcribe_file.post_process_prompt (optional): Same as in transcribe_file.list_modelsShows the active backend configuration, available local models, and the GPT model used for post-processing.
Models are downloaded automatically from HuggingFace on first use and cached locally.
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:
bin in its PATH, so uvx must be referenced by full path.uvx may pick a Python version (e.g. 3.14) for which ctranslate2 — a native dependency of faster-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 uvx
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).
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 install
See CONTRIBUTING.md for the contribution workflow.
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.
MIT — see LICENSE
Transcribe audio locally with faster-whisper or through the OpenAI Whisper API.
{ "mcpServers": { "io.github.zahirinatzuke-whisper-transcribe-mcp": { "command": "uvx", "args": [ "whisper-transcribe-mcp==1.1.3" ], "env": { "OPENAI_API_KEY": "<secret>", "WHISPER_MODEL": "<value>", "WHISPER_POST_PROCESS_MODEL": "<value>" } } }}Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Der Herausgeber nennt diese Umgebungsvariablen: OPENAI_API_KEY, WHISPER_MODEL, WHISPER_POST_PROCESS_MODEL.
Whisper Transcribe läuft lokal über stdio.
Zuletzt geprüft: 2026-11-09. Transcribe audio locally with faster-whisper or through the OpenAI Whisper API.