jackai-stt-mcp 0.1.0

Local MCP server that transcribes audio files with OpenAI — point it at a path, get the text back

jackai-stt-mcp

Transcribe audio files by naming them in chat.

transcribe ~/Downloads/voice.opus

An MCP server that runs on your own machine, so it can open the file directly. No uploading, no copying, no base64. Your OpenAI key never leaves your computer.

Arabic works well, including dialect.

Install

Add this to your MCP client's config. uvx fetches and runs the package on first use — nothing to install by hand.

{
  "servers": {
    "jackai-stt": {
      "command": "uvx",
      "args": ["jackai-stt-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-proj-..."
      }
    }
  }
}

Where the config lives:

Client	File
VS Code	~/Library/Application Support/Code/User/mcp.json (macOS)
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code	.mcp.json in the project, or claude mcp add
Cursor	~/.cursor/mcp.json

Restart the client, then ask it to transcribe something.

Get an API key at platform.openai.com/api-keys. The account needs credit; transcription runs about $0.0045 per minute.

Usage

Say what you want in plain language — the model fills in the arguments.

transcribe ~/Downloads/voice.opus
transcribe the audio in ./recordings/call.m4a
transcribe meeting.mp3 and tell me who said what

The last one needs speaker labels, so ask for the diarize model:

transcribe meeting.mp3 with gpt-4o-transcribe-diarize

Options

Argument	Default	Notes
file_path	—	Path on this machine. Absolute, relative, or ~/....
audio_url	—	Public http(s) URL, downloaded then transcribed.
audio_base64	—	For short clips. Prefer file_path.
model	gpt-transcribe	See the table below.
language	auto-detect	ISO-639-1 (ar, en). Set only if detection is wrong.
prompt	—	Names or jargon likely in the audio, to steer spelling.

Pass exactly one audio source.

Models

Model	Cost/min	Speaker labels
gpt-transcribe (default)	$0.0045	no
gpt-4o-mini-transcribe	$0.003	no
gpt-4o-transcribe	$0.006	no
gpt-4o-transcribe-diarize	$0.006	yes
whisper-1	$0.006	no

gpt-transcribe is OpenAI's recommended model: cheaper than whisper-1 and more accurate. There is no reason to pick whisper-1 unless you need it specifically.

Formats

flac m4a mp3 mp4 mpeg mpga oga ogg wav webm — up to 25 MB.

.opus files work too. OpenAI rejects that extension even though the bytes are what it accepts as .ogg, so this server renames it in flight. WhatsApp voice notes are all .opus, which is exactly the case that would otherwise fail.

Why it runs locally

A remote MCP server cannot read a file you attached in chat. There is no mechanism in the protocol that carries attachments to a server — it has been an open issue since early 2025, and the proposals to add one are still drafts. Base64 through a tool argument works in theory but dies on client argument-size limits after a second or two of audio.

Running on your machine avoids all of it. The server is a process you own, reading a file you own, with a key you hold.

Development

git clone https://github.com/jack-ai-net/stt-mcp
cd stt-mcp
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest

Tests stub the OpenAI call, so they need no API key and cost nothing.

License

MIT — see LICENSE.

Built by JackAI.