Mini Whisper

MCP server for audio transcription using OpenAI Whisper.

Requirements

• Python 3.11+
• uv
• ffmpeg (apt install ffmpeg / brew install ffmpeg)

Install

uv sync

Run

stdio (for local agents)

uv run python -m mini_whisper_mcp --transport stdio

HTTP

uv run python -m mini_whisper_mcp --transport streamable-http --host 0.0.0.0 --port 8000

Docker

docker build -t mini-whisper-mcp .
docker run -p 8000:8000 mini-whisper-mcp

Docker Compose

Create a docker-compose.yml alongside your calling agent:

services:
  mini-whisper-mcp:
    image: mini-whisper-mcp
    build: ./mini-whisper-mcp   # path to this repo
    ports:
      - "8000:8000"
    environment:
      MCP_TRANSPORT: streamable-http
      MCP_HOST: 0.0.0.0
      MCP_PORT: "8000"
    restart: unless-stopped

  your-agent:
    build: ./your-agent
    environment:
      WHISPER_MCP_URL: http://mini-whisper-mcp:8000/mcp
    depends_on:
      - mini-whisper-mcp

docker compose up

The agent connects to the MCP server at http://mini-whisper-mcp:8000/mcp using the service name as hostname.

Configuration

MCP Tools

health_check

Basic server health check. Returns "ok".

transcribe

Models are cached in memory after first load. Larger models are more accurate but slower.

Usage example (calling agent)

import base64

with open("audio.mp3", "rb") as f:
    audio_b64 = base64.b64encode(f.read()).decode()

result = await mcp_client.call_tool("transcribe", {
    "audio_b64": audio_b64,
    "model": "base",
    "suffix": ".mp3",
})

Testing with MCP Inspector

npx @modelcontextprotocol/inspector uv run python -m mini_whisper_mcp --transport stdio

For HTTP, start the server first then connect Inspector to http://localhost:8000/mcp.

Claude Desktop config (stdio)

{
  "mcpServers": {
    "whisper": {
      "command": "uv",
      "args": ["--directory", "/path/to/mini-whisper-mcp", "run", "python", "-m", "mini_whisper_mcp", "--transport", "stdio"]
    }
  }
}

Project structure

mini_whisper_mcp/
├── __main__.py   # CLI entrypoint (--transport, --host, --port)
├── server.py     # MCP tools
└── models.py     # Whisper model loader with CUDA fallback