# whisper-mcp

Local [Whisper](https://github.com/openai/whisper) transcription, exposed as
an [MCP](https://modelcontextprotocol.io) server — so any MCP client (Claude
Desktop, Claude Code, etc.) can transcribe audio/video files, generate `.srt`
subtitles, and burn captions into a video, directly as tool calls. No cloud
API, no manual "run a script and go read the output file" step.

Built on [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) for
inference and `ffmpeg` for audio extraction / caption burn-in.

![Claude Code calling the transcribe tool and returning a timestamped transcript](assets/demo.gif)

## Architecture

```
MCP client (Claude, etc.) --stdio--> whisper-mcp server --> faster-whisper (Whisper model)
                                                        \--> ffmpeg (audio extract / burn-in)
```

The server keeps loaded Whisper models cached in memory for the life of the
process, so repeated tool calls in one session don't re-pay model load time.

## Tools

| Tool | Description |
|---|---|
| `transcribe(path, model_size="small", device="auto")` | Returns detected language + timestamped segments as structured data. |
| `generate_srt(path, output_path=None, model_size="small", device="auto")` | Transcribes and writes a `.srt` file. |
| `burn_captions(video_path, srt_path, output_path=None)` | Burns an `.srt` into a video via `ffmpeg`. |

## Requirements

- Python 3.10+
- `ffmpeg` on `PATH`
- Optional: a CUDA-capable GPU (falls back to CPU automatically)

## Install & run

```bash
pip install -e ".[dev]"
whisper-mcp
```

Or, zero-install:

```bash
uvx --from git+https://github.com/Chain-P/whisper-mcp whisper-mcp
```

## Configure in an MCP client

Add to your client's MCP config (e.g. Claude Code's `.mcp.json` or Claude
Desktop's `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "whisper": {
      "command": "whisper-mcp"
    }
  }
}
```

Then ask the client to transcribe a file, e.g. "transcribe
`samples/podcast_clip.mp4` and give me the SRT."

## Development

```bash
pip install -e ".[dev]"
ruff check .
pytest                        # unit tests only
pytest -m integration         # + real transcription against a sample file
```

## Roadmap

- Speaker diarization (`pyannote.audio` / `whisperx`) for multi-speaker
  labeling in the SRT output.
- MCP progress notifications for long transcriptions.
- A `resource` exposing recent transcript history.

## License

MIT