Python Whisper MCP

Local speech transcription MCP server using faster-whisper. Supports transcription, translation to English, JSON, text, SRT and VTT.

Install

Double-click setup.bat. Nothing else is needed — if the machine has no Python 3.10+, it downloads the official python.org installer and installs it for the current user only, so no administrator rights are involved.

It prints the two paths you need for the MCP configuration when it finishes.

If you already have Python and prefer doing it by hand:

py -3 -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Recommended: 64-bit Python 3.10-3.12. The first call downloads the selected model.

Corporate networks

The first call fetches the model from HuggingFace. Where a MITM proxy intercepts TLS, its root certificate lives only in the Windows certificate store, not in the bundle certifi ships, so the download fails with CERTIFICATE_VERIFY_FAILED: self signed certificate in certificate chain.

server.py calls truststore.inject_into_ssl() at startup, which switches Python over to the OS certificate store and makes the download work. Keep truststore in requirements.txt.

To avoid downloading on every machine, pre-fetch the model once and point WHISPER_DOWNLOAD_ROOT at a shared folder.

Related MCP server: Fast-Whisper-MCP-Server

MCP import parameters

• transport: stdio

• command: D:\my_project\whisper-mcp\.venv\Scripts\python.exe

• args: ["D:\\my_project\\whisper-mcp\\server.py"]

• optional env: WHISPER_MODEL=small, WHISPER_DEVICE=auto, WHISPER_COMPUTE_TYPE=default

• optional env: WHISPER_DOWNLOAD_ROOT=D:\models\whisper

• optional env: WHISPER_ZH_CONVERT=s2twp (Traditional Chinese output, see below)

See mcp.json.example and mcp_config.yaml.example.

my-agent GUI (新增 MCP Server dialog)

inject is for credentials the model should never see — this server needs none.

The dialog has no env field, so WHISPER_MODEL and friends cannot be set there. The defaults (small / auto / default) apply. To change them, edit ~/.my-agent/mcp_config.yaml directly and add an env: block as shown in mcp_config.yaml.example.

Claude Code command:

claude mcp add whisper -- "D:\my_project\whisper-mcp\.venv\Scripts\python.exe" "D:\my_project\whisper-mcp\server.py"
claude mcp list

Remove with claude mcp remove whisper.

Tools

• whisper_transcribe: transcribes a local audio/video file.

• whisper_translate_to_english: translates speech to English.

• whisper_server_info: displays server defaults.

Transcription arguments:

• audio_path required absolute path

• language: zh, en, ja, etc.; empty means auto detect

• model: tiny, base, small, medium, large-v3, turbo

• device: auto, cpu, cuda

• compute_type: default, int8, float16

• beam_size: 1-20

• vad_filter: silence filtering

• word_timestamps: include word timestamps

• initial_prompt: names and domain terminology

• output_format: json, text, srt, vtt

• output_path: save complete output to a local file

• zh_convert: Chinese script conversion, see below

Traditional Chinese

Whisper's Chinese training data is overwhelmingly Simplified, so raw output is Simplified regardless of the speaker. This server converts Chinese results to Traditional Chinese (Taiwan) with OpenCC before returning them.

Conversion runs after recognition, so it never affects accuracy — and it only applies when the detected language is zh and the task is transcription. whisper_translate_to_english output is untouched.

Set the default with WHISPER_ZH_CONVERT, or override per call with the zh_convert argument. If opencc is missing or the config name is invalid, conversion is skipped silently and the raw output is returned.

Example tool input:

{
  "audio_path": "D:\\audio\\meeting.mp3",
  "language": "zh",
  "model": "small",
  "vad_filter": true,
  "output_format": "srt",
  "output_path": "D:\\audio\\meeting.srt"
}

CPU recommendation: small, cpu, int8. NVIDIA GPU: large-v3 or turbo, cuda, float16.

Test with MCP Inspector:

npx @modelcontextprotocol/inspector "D:\my_project\whisper-mcp\.venv\Scripts\python.exe" "D:\my_project\whisper-mcp\server.py"