# STT MCP

> Fast, local speech-to-text MCP server

- **Type:** MCP server
- **Install:** `agentstack add mcp-sm18lr88-stt-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sm18lr88](https://agentstack.voostack.com/s/sm18lr88)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sm18lr88](https://github.com/sm18lr88)
- **Source:** https://github.com/sm18lr88/STT-MCP

## Install

```sh
agentstack add mcp-sm18lr88-stt-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](#backends)
- [Installation](#installation)
- [Transcribe from the CLI](#transcribe-from-the-cli)
- [Use as an MCP server](#use-as-an-mcp-server)
- [Operational behavior](#operational-behavior)
- [Contributor and backend verification](#contributor-and-backend-verification)
- [Contributing](#contributing)
- [License](#license)
- [Uninstall](#uninstall)

## Backends

| Backend  | Best for                                             | Runtime                                                     |
| -------- | ---------------------------------------------------- | ----------------------------------------------------------- |
| Parakeet | CPU-only Windows/Linux, Intel Mac, and Apple Silicon | Pinned `parakeet.cpp` v0.4.0 plus a local multilingual GGUF |
| Granite  | Highest-quality verified CUDA path                   | Pinned IBM Granite Speech model on exactly one NVIDIA GPU   |

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`](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](https://docs.astral.sh/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:

```console
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:

```console
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](docs/SETUP.md#4-install-parakeet), then persist their local paths:

```console
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:

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

Choose formats and an output directory:

```console
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:

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

Other stdio clients can launch the installed Python environment with:

```text
-m stt_mcp.server
```

The server exposes:

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

Omitting `output_directory` writes beside the source. Omitting `formats` publishes every format.

## 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`](docs/SETUP.md#6-run-static-and-default-test-gates). The default project gates are:

```console
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:

```powershell
$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.

```console
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`](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](LICENSE). Parakeet runtime and model assets retain
their separate upstream license and attribution requirements described in
[`docs/SETUP.md`](docs/SETUP.md#4-install-parakeet).

## Uninstall

```console
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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sm18lr88](https://github.com/sm18lr88)
- **Source:** [sm18lr88/STT-MCP](https://github.com/sm18lr88/STT-MCP)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sm18lr88-stt-mcp
- Seller: https://agentstack.voostack.com/s/sm18lr88
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.