Skip to main content
Glama
rhuanca

mini_whisper_mcp

by rhuanca
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

mini-whisper-mcp

MCP server for audio transcription using OpenAI Whisper.

Requirements

  • Python 3.11+

  • uv

  • ffmpeg (apt install ffmpeg / brew install ffmpeg)

Related MCP server: whisper-telegram-mcp

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

Env var

Default

Description

MCP_TRANSPORT

streamable-http

stdio or streamable-http (Docker default)

MCP_HOST

0.0.0.0

Host for HTTP mode

MCP_PORT

8000

Port for HTTP mode

MCP Tools

health_check

Basic server health check. Returns "ok".

transcribe

Param

Type

Default

Description

audio_b64

string

—

Base64-encoded audio file content

model

string

base

tiny, base, small, medium, large

suffix

string

.mp3

File extension hint: .mp3, .wav, .m4a, etc.

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

Available Tools

1 tool
transcribeA

Transcribe a base64-encoded audio file using Whisper.

Args: audio_b64: Base64-encoded audio file content model: Whisper model to use: tiny, base, small, medium, large (default: base) suffix: File extension hint for the audio format, e.g. .mp3, .wav, .m4a (default: .mp3)

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNobase
suffixNo.mp3
audio_b64Yes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It mentions the use of Whisper and parameter details, but does not disclose potential side effects, latency, output format specifics (though an output schema exists), or error conditions. It is adequate but lacks deeper behavioral context. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a one-line summary, followed by a neatly formatted 'Args' list. Every sentence earns its place, with no irrelevant information. The structure is easy to parse and appropriately sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple transcription tool, the description covers the essential details: what it does, input requirements, and parameter semantics. Since an output schema is present, return values need not be explained. Minor gaps exist around limitations (e.g., file size, accuracy), but overall it is sufficiently complete for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has no descriptions (0% coverage), so the description fully compensates by providing detailed explanations for all three parameters. It lists accepted values for 'model' (tiny, base, small, medium, large) with a default, and provides examples for 'suffix' (.mp3, .wav, .m4a) with a default. This adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Transcribe a base64-encoded audio file using Whisper.' The verb 'transcribe' is specific, and the resource (audio file) and method (Whisper) are identified. Although no siblings are provided, the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by specifying the input format (base64-encoded audio) and the Whisper model, giving an agent enough context to invoke it for transcription tasks. However, it does not explicitly mention when not to use it or compare to alternatives, as there are no siblings. The constraints are clear but not exhaustive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.0
    • First observedtranscribe
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of ambiguity. The 'transcribe' tool has a clear and specific purpose for audio transcription.

Naming Consistency5/5

The single tool name 'transcribe' uses a simple verb form, and with no other tools to compare against, naming is consistent by default.

Tool Count3/5

A single tool feels thin for many servers, but for a dedicated 'mini Whisper' transcription service, it is a reasonable scope. It borders on minimal but is not excessive.

Completeness5/5

The tool covers the essential transcription functionality completely, accepting audio input and optional model parameters. There are no obvious missing operations for this narrow domain.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers