STT-MCP

Let your AI agents understand audio files, and audio within video. Normalizes audio with FFMPEG -> translates -> cleans up after itself.

Chosen backend implementation depends on your hardware, and your agent will help you choose: Parakeet or Granite. That selection is persisted for both the CLI and MCP server.

Table of contents

• Backends
• Installation
• Transcribe from the CLI
• Use as an MCP server
• Operational behavior
• Contributor and backend verification
• Contributing
• License
• Uninstall

Backends

Windows x86-64 is verified with Parakeet CPU and Granite CUDA SDPA. Linux, WSL2, Intel macOS, and Apple Silicon paths are implemented but remain runtime-unverified. Containers are unsupported.

Installation

The recommended installation path is to point your coding agent at the authoritative runbook. Copy and paste this instruction into your agent:

Read docs/SETUP.md from top to bottom. Inspect my hardware, show me the recommended backend and why, ask me to confirm or choose a supported alternative, then follow the runbook to install, configure, and verify STT-MCP. Do not silently choose a backend or skip the real speech acceptance test.

The agent must pause for your backend confirmation before installing backend-specific assets. If you prefer a manual installation, follow the same runbook directly. Before continuing, install:

• uv with managed CPython 3.13;
• ffmpeg and ffprobe on PATH;
• enough storage for the selected runtime and model.

Dependency and model installation also require network access. Prepare the project and inspect the machine:

uv --version
uv python install 3.13
ffmpeg -version
ffprobe -version
uv sync --python 3.13 --locked
uv run stt-mcp setup inspect

Review the JSON recommendation, then confirm the backend before installing or configuring it. setup inspect never changes configuration.

Granite

Granite requires a supported NVIDIA/CUDA environment and the optional dependency group:

uv sync --python 3.13 --locked --extra granite
uv run stt-mcp setup configure --backend granite

Parakeet

Download and verify the exact executable and model from the Parakeet setup instructions, then persist their local paths:

uv run stt-mcp setup configure --backend parakeet \
  --parakeet-executable "/path/to/parakeet-cli" \
  --parakeet-model "/path/to/tdt-0.6b-v3-q4_k.gguf" \
  --parakeet-device cpu

Parakeet binaries and models are downloaded only during explicit setup, never at runtime.

Transcribe from the CLI

Publish TXT, Markdown, JSON, SRT, and WebVTT beside the source:

uv run stt-mcp transcribe "/path/to/media.mp4"

Choose formats and an output directory:

uv run stt-mcp transcribe "/path/to/media.mp4" --output "/path/to/transcripts" --format json --format srt

JSON output includes the effective backend. Subtitle timing is coarse 30-second source-window timing for consistent behavior across both backends.

Use as an MCP server

Register a supported client, then restart it:

uv run stt-mcp register opencode
uv run stt-mcp register claude-desktop

Other stdio clients can launch the installed Python environment with:

-m stt_mcp.server

The server exposes:

transcribe(
  source_path: string,
  output_directory?: string,
  formats?: ("txt" | "md" | "json" | "srt" | "vtt")[]
)

start_transcription(
  job_id: UUID,
  source_path: string,
  output_directory?: string,
  formats?: ("txt" | "md" | "json" | "srt" | "vtt")[]
)

get_transcription_status(job_id: UUID)
cancel_transcription(job_id: UUID)

Omitting output_directory writes beside the source. Omitting formats publishes every format. Use start_transcription for long media, then poll get_transcription_status with the same caller-generated UUID. Repeating start_transcription with the same UUID and inputs is idempotent; reusing it with different inputs is rejected. Completed, failed, and cancelled jobs retain their terminal result or error for later status calls during the server process lifetime.

Operational behavior

• One backend is selected and latched for the MCP process.
• One transcription runs at a time; concurrent requests fail immediately as busy.
• Explicit Granite remains fail-closed under its CUDA/NVML safety policy.
• Cancellation closes the active Parakeet process or invalidates the Granite worker.
• Artifacts are atomically published, so failed requests do not leave partial output.
• Runtime code never downloads Parakeet assets.
• Granite loads only when selected; Parakeet-only imports do not load Torch, Transformers, or NVML.

Contributor and backend verification

The authoritative verification and real-acceptance sequence is in docs/SETUP.md. The default project gates are:

uv sync --python 3.13 --locked --extra granite
uv run ruff check .
uv run basedpyright
uv run ty check src tests
uv run mypy
uv run pytest
uv build

Run real acceptance with the configured backend:

$env:STT_MCP_TEST_MEDIA = (Resolve-Path "D:\path\to\speech.wav").Path
uv run pytest tests/test_mcp_acceptance.py -q -s
Remove-Item Env:STT_MCP_TEST_MEDIA

Where GNU Make is available, local convenience targets mirror those commands without replacing the authoritative runbook. On Windows systems without Make, run the direct uv commands above.

make test-fast
make lint
make test
make coverage
make build
make pmat

Install the fast Ruff pre-commit checks with make hooks. PMAT dead-code analysis should target src; its Python analyzer reports decorated Typer commands, Pydantic validators, Protocol members, and interface properties as medium-confidence dead code even though those entry points are live.

Hosted CI/CD is intentionally not configured. Backend setup and acceptance depend on the user's hardware, a user-confirmed backend, exact local model assets, and a real speech sample, so the setup agent executes the runbook on the target computer.

Contributing

Keep changes focused, use uv exclusively, and run the full local quality gates before handing work off (make quality where GNU Make is available). Changes to setup, backend selection, CUDA policy, model pins, or client registration must also follow docs/SETUP.md and complete the applicable real CLI and MCP acceptance steps.

Do not weaken Granite's fail-closed GPU checks, introduce runtime model downloads, or claim an unverified platform/backend pair works.

License

This project is licensed under the MIT License. Parakeet runtime and model assets retain their separate upstream license and attribution requirements described in docs/SETUP.md.

Uninstall

uv run stt-mcp unregister opencode
uv run stt-mcp unregister claude-desktop

The repository workflow installs STT-MCP into .venv through uv sync; it does not create a uv tool installation. Delete .venv only if you also want to remove that project environment. Transcripts, configuration, model caches, and downloaded Parakeet assets remain until you remove them explicitly.