Local Whisper README

Private, local audio transcription for Claude. Local Whisper is a Model Context Protocol (MCP) server that transcribes audio files with Whisper on your own computer, so voice notes, meetings, and lectures never leave it. It works in Claude Desktop, in Claude Code, and in claude.ai chats that run on your computer.

https://github.com/user-attachments/assets/dc71b178-b60d-457e-8f33-732696671c02

Features

• Transcribes WAV, Ogg Opus (WhatsApp and Telegram voice notes), and MP3 files with no extra software. With ffmpeg on the PATH, it also reads M4A and FLAC.
• Transcribes videos, such as MP4 and WebM files, when ffmpeg is installed: the server takes the audio track and ignores the picture. Turn a recorded meeting or class into text or subtitles without extracting the audio first.
• Runs on the GPU through Vulkan on Windows and Linux and through Metal on Apple Silicon, and falls back to the CPU on its own. With the default model, large-v3-turbo-q8_0, an NVIDIA GeForce RTX 3080 transcribes a minute of audio in about one second.
• Downloads the model the first time it's needed, checks it against the hash that Hugging Face publishes, and frees its memory, including GPU memory, after 5 minutes without use.
• Returns plain text, SubRip subtitles (SRT), or JSON segments with timestamps.
• Skips silence with voice activity detection on clean recordings, which keeps timestamps exact, and transcribes everything when background noise could hide quiet speech.
• Ships as one native executable per platform: there's no Python or .NET runtime to install.

Install

Find your system in the following table, and download the file for the app where you use Claude. Each link downloads the file from the latest release.

The skill tells Claude when and how to use the server. For more information, see The skill.

To check which Mac you have, choose Apple menu > About This Mac. A Chip line that starts with Apple, such as Apple M2, means Apple Silicon. A Processor line that names Intel means an Intel processor.

Claude Desktop for Linux is a beta for Ubuntu and Debian.

To verify a download, compare its SHA-256 hash with the one in SHA256SUMS.txt, on the releases page.

Claude Desktop

To add Local Whisper to Claude Desktop, install its extension:

1. Download the extension for your system from the table in Install.
2. Open the file. Claude Desktop shows the extension's details.
3. Click Install.
4. Optional: In the extension's settings, choose the folders with your audio, the model, and the language.

Claude Code

To add Local Whisper to Claude Code, register the executable as an MCP server:

1. Download the archive for your system from the table in Install, and extract it to a folder that you keep.

2. Run the following command:

   TerminalCopy

   claude mcp add local-whisper -- PATH_TO_EXECUTABLE
   

   Replace PATH_TO_EXECUTABLE with the full path of local-whisper-mcp (or local-whisper-mcp.exe on Windows) in that folder.

To change a setting, add it to the command as an environment variable, for example claude mcp add local-whisper -e LOCAL_WHISPER_LANGUAGE=es -- PATH_TO_EXECUTABLE.

claude.ai chats on your computer

A claude.ai chat reaches the server through the Claude desktop app on your computer:

1. Install the extension in Claude Desktop, as described in Claude Desktop.
2. When you start a chat in claude.ai, click + in the message box, choose Devices, and pick your computer under Run tasks on. The computer has to be on, with the Claude desktop app open.
3. Attach the audio and ask Claude to transcribe it. Claude copies the file into the server's inbox folder, and the server deletes the copy after transcribing it.

The skill

The skill is optional, and recommended. The server works without it, but the skill tells Claude when to use the server, how to pass it a chat attachment, and what to tell you when the server isn't reachable. Without it, a claude.ai chat that doesn't run on your computer can't see the server and may try to transcribe the audio in the cloud instead of telling you how to connect it.

To add the skill to claude.ai and Claude Desktop, download local-whisper-skill.zip and upload it in Settings > Capabilities, under Skills.

To add the skill to Claude Code, install the local-whisper plugin from the orihuelaconde marketplace. First, add the marketplace:

claude plugin marketplace add OrihuelaConde/claude-plugins

Then install the plugin:

claude plugin install local-whisper@orihuelaconde

The plugin carries only the skill; register the server as described in Claude Code.

Use

Ask Claude in your own words. For example:

• "Transcribe the voice note I just attached."
• "Transcribe C:\Users\me\Recordings\meeting.m4a and summarize the decisions."
• "Make Spanish subtitles for ~/Videos/class.mp4."
• "Transcribe the interview with Mirtha Legrand from her lunch show."

Video files are much larger than audio files. When a video is already on your computer, give Claude its path instead of attaching it to the chat, so it doesn't have to travel through the chat and back.

The server provides three tools:

When you name the people, places, or products in a recording, Claude can pass up to about eight of them to transcribe as hints, and Whisper spells them the way you wrote them. Hints help most with uncommon names, which Whisper otherwise spells by ear. The server takes hints from version 1.1.0.

Configure

The Claude Desktop extension shows these settings on its page. For Claude Code and other MCP clients, set them as environment variables:

To download a model before its first use, for example on a slow connection, run the executable with the download command:

local-whisper-mcp download large-v3-turbo-q8_0

Privacy

• Transcription runs on your computer. The server goes online only to download models from Hugging Face, which you can turn off with LOCAL_WHISPER_AUTO_DOWNLOAD=false.
• The server reads audio only inside the allowed folders and the inbox, and it deletes only files in the inbox: each one after transcribing it, and any left there for more than a day.
• The log in ~/.local-whisper-mcp/logs records timings, settings, and errors, never transcripts. Routine entries leave out file names, but an error entry can include the path of the file that failed, so review the log before you share it. The server keeps a week of logs.

Requirements

• Windows 10 or later (x64), macOS (Apple Silicon or Intel), or Linux (x64 or arm64).
• On x64, a processor with AVX2.
• For the GPU: a Vulkan driver on Windows and Linux x64, or Apple Silicon for Metal. Without one, the server uses the CPU.
• On Linux, the OpenMP runtime: sudo apt install libgomp1 on Debian and Ubuntu.
• Optional: ffmpeg, for formats other than WAV, Ogg Opus, and MP3.

The release files aren't signed. On macOS, if Gatekeeper blocks the executable from the archive, allow it with xattr -dr com.apple.quarantine FOLDER, where FOLDER is the extracted folder.

Troubleshoot

• The first transcription takes minutes. The server is downloading the model, about 900 MB for the default one. Claude can follow the download with the status tool.
• The first transcription on a Mac with Apple Silicon takes about 15 seconds more. macOS compiles the GPU shaders once per computer.
• Parts of a recording are missing. Ask Claude to transcribe it again with vad set to false.
• A long recording repeats a phrase over and over in the transcript. If Claude passed hints, ask it to transcribe the recording again without them.
• Something else fails. Check today's file in ~/.local-whisper-mcp/logs.

Build from source

You need the .NET 10 SDK and the Native AOT prerequisites for your system. To run the tests, publish the server, and pack the Claude Desktop extension, run these commands from the repository root:

dotnet test --project tests/LocalWhisperMcp.Tests

dotnet publish src/LocalWhisperMcp -c Release -r win-x64 -o out

pwsh packaging/mcpb/pack.ps1 -Rid win-x64 -PublishDir out

Replace win-x64 with the runtime identifier of your system: osx-arm64, osx-x64, linux-x64, or linux-arm64. Native AOT builds only for the system it runs on.

Design notes

The measurements behind the server's design are in the repository:

• Proof-of-concept results: why the server is a C# Native AOT executable with Whisper.net, and how the default model, the GPU backend, and the audio decoders were chosen.
• Gemma 4 as an alternative engine: Gemma 4 E2B, E4B, and 12B compared with Whisper on public test sets with reference transcripts. Whisper stays the only engine: it makes fewer errors, and on computers without a GPU the Whisper small model matches Gemma 4.
• Hints: what passing the names in a recording as a Whisper prompt does to the transcript, and why the list is limited to 120 characters.

License

Local Whisper is released under the MIT License. It includes components under their own licenses, listed in THIRD-PARTY-NOTICES.txt.

Local Whisper is an independent project, not affiliated with or endorsed by Anthropic or OpenAI. Claude is a trademark of Anthropic, PBC, and this project uses the name only to say which apps it works with.