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 | sh

Option 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.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.

Linux

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.

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-v3

Case 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:

Add the entry inside "mcpServers":

Windows note: Claude Desktop runs in a restricted environment and may not have uvx in its PATH, and it may use a Python version (e.g. 3.14) for which ctranslate2 (a dependency of faster-whisper) does not yet have prebuilt wheels. Two fixes are required:

1. Use the full path to uvx.exe instead of just uvx. Run where.exe uvx in PowerShell to find it (usually C:\Users\<YourUser>\.local\bin\uvx.exe).
2. Force Python 3.12 via the --python 3.12 flag 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:

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.12 before the package name to avoid ctranslate2 wheel issues. Edit ~/.claude.json directly 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

Backend selection and fallback ([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.

Security and Permissions

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.

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 file
• language (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.