{
  "markdown": "<!-- mcp-name: io.github.ZahiriNatZuke/whisper-transcribe-mcp -->\n\n# whisper-transcribe-mcp\n\n[![PyPI version](https://img.shields.io/pypi/v/whisper-transcribe-mcp)](https://pypi.org/project/whisper-transcribe-mcp/)\n[![CI](https://github.com/ZahiriNatZuke/whisper-transcribe-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ZahiriNatZuke/whisper-transcribe-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)\n\nMCP 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.\n\n---\n\n## Prerequisites\n\n### macOS\n\n**Option A — uv (recommended):**\n```bash\nbrew install uv\n# or\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n**Option B — Python:**\nPython 3.10+ is included in macOS 12.3+. You can also install it with `brew install python`.\n\n---\n\n### Windows\n\n**Option A — uv (recommended):**\n```powershell\nwinget install astral-sh.uv\n```\nOr download the installer from [astral.sh/uv](https://astral.sh/uv).\n\n**Option B — Python:**\nDownload Python 3.10+ from [python.org](https://python.org). During installation, check **\"Add Python to PATH\"**.\n\n> No need to install ffmpeg or any compiler — everything is bundled in the package.\n\n---\n\n### Linux\n\n**Option A — uv (recommended):**\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n**Option B — Python:**\n```bash\n# Debian/Ubuntu\nsudo apt install python3.12 python3.12-venv\n\n# Fedora\nsudo dnf install python3.12\n\n# Arch\nsudo pacman -S python\n```\n\n> No additional system dependencies required.\n\n---\n\n## Installation\n\n### Option A — uvx (recommended, no permanent install)\n\n`uvx` automatically downloads and installs the package in an isolated environment. Only requires `uv` to be installed.\n\n```bash\n# Local backend:\nuvx \"whisper-transcribe-mcp[local]\"\n\n# OpenAI backend:\nuvx \"whisper-transcribe-mcp[openai]\"\n\n# Both backends:\nuvx \"whisper-transcribe-mcp[all]\"\n```\n\n### Option B — pip\n\n```bash\n# Local backend:\npip install \"whisper-transcribe-mcp[local]\"\n\n# OpenAI backend:\npip install \"whisper-transcribe-mcp[openai]\"\n\n# Both backends:\npip install \"whisper-transcribe-mcp[all]\"\n```\n\n---\n\n## Use Cases\n\n### Case 1 — Local backend only (free, works offline)\n\nUses `faster-whisper` to transcribe locally. The model is downloaded from HuggingFace on first use (~74MB for `base`) and cached.\n\n**Install:**\n```bash\npip install \"whisper-transcribe-mcp[local]\"\n```\n\n**Environment variables:**\n```\nWHISPER_MODEL=base   # or tiny, small, medium, large-v3\n```\n\n---\n\n### Case 2 — OpenAI backend only (best accuracy, requires API key)\n\nUses OpenAI's `whisper-1` model. Requires an API key and internet connection. No local model downloads.\n\n**Install:**\n```bash\npip install \"whisper-transcribe-mcp[openai]\"\n```\n\n**Environment variables:**\n```\nOPENAI_API_KEY=sk-...\n```\n\n---\n\n### Case 3 — Both backends (OpenAI if key present, local as fallback)\n\nIf `OPENAI_API_KEY` is set, OpenAI is used automatically. Otherwise falls back to local faster-whisper.\n\n**Install:**\n```bash\npip install \"whisper-transcribe-mcp[all]\"\n```\n\n---\n\n## Configuration\n\n### Claude Desktop\n\nConfig file location by operating system:\n\n| OS | Path |\n|---|---|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\nAdd the entry inside `\"mcpServers\"`:\n\n> **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:\n> 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`).\n> 2. Force Python 3.12 via the `--python 3.12` flag so that a compatible wheel is used.\n\n**Case 1 — Local:**\n\nmacOS / Linux:\n```json\n{\n  \"mcpServers\": {\n    \"whisper-transcribe\": {\n      \"command\": \"uvx\",\n      \"args\": [\"whisper-transcribe-mcp[local]\"],\n      \"env\": {\n        \"WHISPER_MODEL\": \"base\"\n      }\n    }\n  }\n}\n```\n\nWindows:\n```json\n{\n  \"mcpServers\": {\n    \"whisper-transcribe\": {\n      \"command\": \"C:\\\\Users\\\\<YourUser>\\\\.local\\\\bin\\\\uvx.exe\",\n      \"args\": [\"--python\", \"3.12\", \"whisper-transcribe-mcp[local]\"],\n      \"env\": {\n        \"WHISPER_MODEL\": \"base\"\n      }\n    }\n  }\n}\n```\n\n**Case 2 — OpenAI:**\n\nmacOS / Linux:\n```json\n{\n  \"mcpServers\": {\n    \"whisper-transcribe\": {\n      \"command\": \"uvx\",\n      \"args\": [\"whisper-transcribe-mcp[openai]\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"sk-...\"\n      }\n    }\n  }\n}\n```\n\nWindows:\n```json\n{\n  \"mcpServers\": {\n    \"whisper-transcribe\": {\n      \"command\": \"C:\\\\Users\\\\<YourUser>\\\\.local\\\\bin\\\\uvx.exe\",\n      \"args\": [\"--python\", \"3.12\", \"whisper-transcribe-mcp[openai]\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"sk-...\"\n      }\n    }\n  }\n}\n```\n\n**Case 3 — Both (OpenAI takes priority if key is set):**\n\nmacOS / Linux:\n```json\n{\n  \"mcpServers\": {\n    \"whisper-transcribe\": {\n      \"command\": \"uvx\",\n      \"args\": [\"whisper-transcribe-mcp[all]\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"sk-...\",\n        \"WHISPER_MODEL\": \"base\"\n      }\n    }\n  }\n}\n```\n\nWindows:\n```json\n{\n  \"mcpServers\": {\n    \"whisper-transcribe\": {\n      \"command\": \"C:\\\\Users\\\\<YourUser>\\\\.local\\\\bin\\\\uvx.exe\",\n      \"args\": [\"--python\", \"3.12\", \"whisper-transcribe-mcp[all]\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"sk-...\",\n        \"WHISPER_MODEL\": \"base\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after editing the file.\n\n---\n\n### Claude Code\n\nWorks the same on macOS, Windows, and Linux. Requires `uv` installed.\n\nClaude Code config file location:\n\n| OS | Global | Per project |\n|---|---|---|\n| macOS / Linux | `~/.claude.json` | `.claude/settings.json` (project root) |\n| Windows | `C:\\Users\\<user>\\.claude.json` | `.claude\\settings.json` (project root) |\n\nThe easiest way to add the server is via the Claude Code CLI, which updates the config file automatically:\n\n```bash\n# Case 1 — Local:\nclaude mcp add whisper-transcribe uvx -- \"whisper-transcribe-mcp[local]\"\n\n# Case 2 — OpenAI:\nclaude mcp add whisper-transcribe uvx --env OPENAI_API_KEY=sk-... -- \"whisper-transcribe-mcp[openai]\"\n\n# Case 3 — Both (OpenAI with local fallback):\nclaude mcp add whisper-transcribe uvx --env OPENAI_API_KEY=sk-... --env WHISPER_MODEL=base -- \"whisper-transcribe-mcp[all]\"\n```\n\n> **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]\"]`.\n\nTo add it globally (available in all projects), use `--scope user`:\n\n```bash\nclaude mcp add --scope user whisper-transcribe uvx -- \"whisper-transcribe-mcp[local]\"\n```\n\nOr edit `~/.claude.json` directly and add inside `\"mcpServers\"`:\n\n```json\n{\n  \"mcpServers\": {\n    \"whisper-transcribe\": {\n      \"command\": \"uvx\",\n      \"args\": [\"whisper-transcribe-mcp[local]\"],\n      \"env\": {\n        \"WHISPER_MODEL\": \"base\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Environment Variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `WHISPER_MODEL` | `base` | Local model size: `tiny`, `base`, `small`, `medium`, `large-v3` |\n| `OPENAI_API_KEY` | — | If set, activates the OpenAI backend instead of local |\n\n### Backend selection and fallback (`[all]` only)\n\nWhen installed with `[all]`, the backend is chosen at startup:\n\n- `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.\n- `OPENAI_API_KEY` **not set** → local `faster-whisper` is used directly, no fallback attempted.\n\n---\n\n## Available Tools\n\n### `transcribe_file`\nTranscribes an audio file by path (mp3, wav, m4a, ogg, flac, webm, etc.).\n\n**Parameters:**\n- `file_path` (required): Absolute path to the audio file\n- `language` (optional): Language code (`es`, `en`, `fr`, etc.). Auto-detected if not provided.\n- `model_size` (optional): Local model size. Ignored with the OpenAI backend.\n- `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]`).\n- `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.\n\n**Response (without post-processing):**\n```json\n{\n  \"text\": \"Full transcription...\",\n  \"language\": \"en\",\n  \"language_probability\": 0.99,\n  \"segments\": [\n    { \"start\": 0.0, \"end\": 4.2, \"text\": \"First segment...\" }\n  ],\n  \"backend\": \"local\",\n  \"model\": \"base\"\n}\n```\n\n**Response (with `post_process: true`):**\n```json\n{\n  \"text\": \"Corrected transcription...\",\n  \"raw_text\": \"Original transcription from Whisper...\",\n  \"post_process_model\": \"gpt-4.1\",\n  \"language\": \"en\",\n  \"language_probability\": 0.99,\n  \"segments\": [...],\n  \"backend\": \"local\",\n  \"model\": \"base\"\n}\n```\n\nIf post-processing fails, `text` retains the original transcription and a `post_process_error` field is added.\n\n---\n\n### `transcribe_base64`\nTranscribes audio provided as a base64-encoded string. Useful for programmatic integrations.\n\n**Parameters:**\n- `audio_base64` (required): Base64-encoded audio data\n- `extension` (optional, default `mp3`): File extension (`mp3`, `wav`, `ogg`, etc.)\n- `language` (optional): Language code\n- `model_size` (optional): Local model size\n- `post_process` (optional, default `false`): Same as in `transcribe_file`.\n- `post_process_prompt` (optional): Same as in `transcribe_file`.\n\n---\n\n### `list_models`\nShows the active backend configuration, available local models, and the GPT model used for post-processing.\n\n---\n\n## Local Model Sizes\n\n| Model | Size | Relative Speed | Notes |\n|---|---|---|---|\n| `tiny` | 39 MB | ~32x | Fastest, least accurate |\n| `base` | 74 MB | ~16x | Good balance (default) |\n| `small` | 244 MB | ~6x | Better accuracy |\n| `medium` | 769 MB | ~2x | High accuracy |\n| `large-v3` | 1.5 GB | ~1x | Best accuracy, slowest |\n\nModels are downloaded automatically from HuggingFace on first use and cached locally.\n\n---\n\n## Troubleshooting\n\n### MCP not loading in Claude Desktop on Windows\n\n**Symptom:** The server fails to start with a dependency resolution error like:\n\n```\nctranslate2>=4.6.1 has no wheels with a matching platform tag (e.g., `win32`)\nhint: You require CPython 3.14 (`cp314`), but we only found wheels for `ctranslate2` with: `cp39`, `cp310`, `cp311`, `cp312`, `cp313`\n```\n\n**Cause:** Two issues combined:\n1. Claude Desktop does not include the user's local `bin` in its PATH, so `uvx` must be referenced by full path.\n2. Claude Desktop's `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.\n\n**Fix:** Use the full path to `uvx.exe` and force Python 3.12 explicitly:\n\n```json\n\"whisper-transcribe\": {\n  \"command\": \"C:\\\\Users\\\\<YourUser>\\\\.local\\\\bin\\\\uvx.exe\",\n  \"args\": [\"--python\", \"3.12\", \"whisper-transcribe-mcp[local]\"],\n  \"env\": { \"WHISPER_MODEL\": \"base\" }\n}\n```\n\nTo find your exact `uvx.exe` path, run in PowerShell:\n```powershell\nwhere.exe uvx\n```\n\n### Transcribing audio files in Claude Desktop\n\n**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.\n\n**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.\n\n**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:\n\n> *\"Transcribe the file at `C:\\Users\\YourUser\\Downloads\\audio.mp3`\"*\n\nThe 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).\n\n---\n\n## Development\n\nThis project uses [`uv`](https://docs.astral.sh/uv/) for reproducible development environments:\n\n```bash\nuv sync --group dev\nuv run ruff check .\nuv run ruff format --check .\nuv run pytest -q\nuv run pre-commit install\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.\n\n## Distribution and releases\n\nThe package is distributed through [PyPI](https://pypi.org/project/whisper-transcribe-mcp/) and\ndescribed by `server.json` for the\n[official MCP Registry](https://registry.modelcontextprotocol.io/). Version tags publish both\ndestinations through GitHub OIDC, without long-lived publishing tokens. See\n[docs/publishing.md](docs/publishing.md) for the release checklist and one-time repository setup.\n\nThe Registry entry describes the base PyPI package. Choose the `[local]`, `[openai]`, or `[all]`\nextra from the installation examples above so the transcription backend you need is installed.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n",
  "bytes": 13828,
  "sha": "357064aa8806b145634a150b74bd132dfc85eabd7181d86734bbe9f5e5f3db31",
  "repo_slug": "zahirinatzuke/whisper-transcribe-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_zahirinatzuke_whisper_transcri_1049d399/readme"
}