whisper-windows-mcp 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 whisper-windows-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,235 @@
+# whisper-windows-mcp
+
+A Windows-native MCP (Model Context Protocol) server that lets Claude Desktop transcribe audio files locally using [whisper.cpp](https://github.com/ggerganov/whisper.cpp) — no internet connection required, no data sent to the cloud.
+
+> **Why does this exist?**
+> The popular `whisper-mcp` package was built for macOS and assumes a Unix environment. It does not work on Windows. This package was written specifically for Windows users who want the same local transcription functionality in Claude Desktop.
+
+---
+
+## What you can do with it
+
+Once installed, you can say things like this directly in Claude Desktop:
+
+- *"Transcribe C:\Users\Me\Downloads\meeting.mp3"*
+- *"Transcribe this recording and summarise the key points"*
+- *"Transcribe with timestamps so I can find specific moments"*
+
+Everything runs on your own machine. No audio ever leaves your computer.
+
+---
+
+## Requirements
+
+You need the following installed before proceeding. Each one is free.
+
+| Requirement | Purpose |
+|---|---|
+| [Node.js 18+](https://nodejs.org/en/download) | Runs the MCP server |
+| [whisper.cpp](https://github.com/ggerganov/whisper.cpp/releases/latest) | The transcription engine |
+| A Whisper model file | The AI model (downloaded in Step 2) |
+
+---
+
+## Step 1 — Install whisper.cpp
+
+1. Go to the [whisper.cpp latest release](https://github.com/ggerganov/whisper.cpp/releases/latest)
+2. Download the file named **`whisper-bin-x64.zip`** (look for `win` and `x64` in the filename)
+3. Extract the ZIP and move the contents to **`C:\whisper\Release\`** — create this folder if it doesn't exist
+
+✅ You should now have **`C:\whisper\Release\whisper-cli.exe`**
+
+> **Why this path?** You can install whisper.cpp anywhere, but `C:\whisper\Release\` matches the default config below and means less to edit later.
+
+---
+
+## Step 2 — Download a Whisper model
+
+The model is the AI that does the actual transcription. Click a link below to download directly:
+
+| Model | Download | Size | Speed | Best for |
+|---|---|---|---|---|
+| tiny.en | [Download](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin) | 75 MB | Very fast | Quick tests |
+| **base.en** | [**Download**](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin) | 142 MB | Fast | **Recommended starting point** |
+| small.en | [Download](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin) | 466 MB | Moderate | Better accuracy |
+| medium.en | [Download](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.en.bin) | 1.5 GB | Slow | High accuracy |
+| large-v3 | [Download](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin) | 2.9 GB | Very slow | Maximum accuracy |
+
+Save the downloaded `.bin` file to **`C:\whisper\models\`** — create this folder if it doesn't exist.
+
+✅ You should now have something like **`C:\whisper\models\ggml-base.en.bin`**
+
+---
+
+## Step 3 — Install Node.js
+
+If you don't already have Node.js:
+
+1. Go to [nodejs.org](https://nodejs.org/en/download) and download the **Windows Installer (.msi)** — choose the LTS version
+2. Run the installer and accept all defaults
+
+✅ To verify, open Command Prompt and run `node --version` — you should see something like `v20.x.x`
+
+---
+
+## Step 4 — Configure Claude Desktop
+
+1. Open Claude Desktop → **Settings → Developer → Edit Config**
+2. Add the following (or merge the `mcpServers` block if you already have other servers):
+
+```json
+{
+  "mcpServers": {
+    "whisper": {
+      "command": "npx",
+      "args": ["-y", "whisper-windows-mcp"],
+      "env": {
+        "WHISPER_CLI_PATH": "C:\\whisper\\Release\\whisper-cli.exe",
+        "WHISPER_MODEL": "C:\\whisper\\models\\ggml-base.en.bin"
+      }
+    }
+  }
+}
+```
+
+> ⚠️ **Path format:** In the JSON config, all backslashes must be doubled (`\\`). This is a JSON requirement. When typing paths into Claude in chat, use normal single backslashes.
+
+3. If you downloaded a different model, update `ggml-base.en.bin` to match your filename
+4. Save the file, fully quit Claude Desktop, and reopen it
+5. Go to **Settings → Developer** — you should see **whisper** with a green **running** badge
+
+---
+
+## Step 5 — Test it
+
+In Claude Desktop, type:
+
+> *"Can you check your whisper config?"*
+
+Claude will verify that `whisper-cli.exe` and your model file are both found. Then try:
+
+> *"Please transcribe C:\Users\YourName\Downloads\recording.mp3"*
+
+---
+
+## Converting video files to audio
+
+Whisper processes audio. If you have a video file (MP4, MKV, etc.) you may want to extract the audio first — audio-only files are much smaller and faster to process.
+
+> **Tip:** whisper.cpp may handle MP4 files directly if FFmpeg is installed. Try transcribing an MP4 first before converting.
+
+**Using VLC Media Player** (free, recommended for beginners):
+
+1. Download [VLC](https://www.videolan.org/vlc/) if you don't have it
+2. Open VLC → **Media → Convert / Save**
+3. Click **Add**, select your video, then click **Convert / Save**
+4. Under **Profile**, choose **Audio - MP3**
+5. Set a destination filename and click **Start**
+
+A 1-hour MP4 that might be 2–4 GB typically becomes a 50–100 MB MP3.
+
+**Using FFmpeg** (command line, for advanced users):
+```
+ffmpeg -i "C:\path\to\video.mp4" -vn -ac 1 -ar 16000 "C:\path\to\output.wav"
+```
+
+---
+
+## Output formats
+
+| Format | What you get | Ask Claude... |
+|---|---|---|
+| `text` (default) | Plain transcript, no timestamps | *"Transcribe this file"* |
+| `timestamps` | Transcript with `[00:00:00 --> 00:00:05]` time codes | *"Transcribe with timestamps"* |
+| `json` | Structured data | *"Transcribe as JSON"* |
+
+---
+
+## Transcription speed
+
+Whisper runs on CPU by default. Rough estimates for a 1-hour recording:
+
+| Model | Approximate time (CPU) |
+|---|---|
+| tiny.en | 5–10 minutes |
+| base.en | 10–20 minutes |
+| small.en | 20–35 minutes |
+| medium.en | 35–60 minutes |
+| large-v3 | 60–120 minutes |
+
+> **GPU acceleration** for AMD (ROCm) and NVIDIA (CUDA) on Windows is planned for a future update.
+
+---
+
+## Full config example
+
+If you have other MCP servers already configured:
+
+```json
+{
+  "preferences": {
+    "coworkWebSearchEnabled": true
+  },
+  "mcpServers": {
+    "whisper": {
+      "command": "npx",
+      "args": ["-y", "whisper-windows-mcp"],
+      "env": {
+        "WHISPER_CLI_PATH": "C:\\whisper\\Release\\whisper-cli.exe",
+        "WHISPER_MODEL": "C:\\whisper\\models\\ggml-base.en.bin"
+      }
+    }
+  }
+}
+```
+
+Config file location:
+```
+C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json
+```
+
+> The `AppData` folder is hidden by default. To show it: File Explorer → **View → Show → Hidden items**
+
+---
+
+## Tested on
+
+- Windows 10 Pro (10.0.19045)
+- Windows 11 — untested, feedback welcome via [Issues](../../issues)
+
+---
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed solutions.
+
+Quick checklist:
+
+- [ ] Config paths use **double backslashes** (`C:\\whisper\\...`)
+- [ ] `whisper-cli.exe` exists at the path specified
+- [ ] The model `.bin` file exists at the path specified
+- [ ] Claude Desktop was **fully restarted** after editing the config
+- [ ] Whisper shows **running** in Settings → Developer
+
+---
+
+## Roadmap
+
+- [ ] SRT subtitle output
+- [ ] Direct MP4/video file support via FFmpeg
+- [ ] Translation to English from other languages
+- [ ] AMD GPU acceleration (ROCm)
+- [ ] NVIDIA GPU acceleration (CUDA)
+- [ ] Speaker diarization (automatic speaker identification)
+
+---
+
+## License
+
+MIT — free to use, modify, and distribute.
+
+---
+
+## Contributing
+
+Pull requests welcome. GPU acceleration solutions for AMD or NVIDIA especially appreciated. Windows 11 feedback welcome via Issues.

package/TROUBLESHOOTING.md

@@ -0,0 +1,136 @@
+# Troubleshooting
+
+This document covers the most common issues encountered when setting up `whisper-windows-mcp` on Windows.
+
+---
+
+## "whisper-cli not found" error
+
+**Symptom:** Claude reports `whisper-cli not found` or suggests running `brew install whisper-cpp`.
+
+**What's happening:** The `brew install` suggestion is a macOS instruction and does not apply to Windows. This error means the MCP server cannot locate `whisper-cli.exe`.
+
+**Fix:** Make sure `WHISPER_CLI_PATH` in your `claude_desktop_config.json` points to the exact location of `whisper-cli.exe` on your system, using double backslashes:
+
+```json
+"WHISPER_CLI_PATH": "C:\\whisper\\Release\\whisper-cli.exe"
+```
+
+Verify the file actually exists at that path by opening File Explorer and navigating there.
+
+---
+
+## "File not found" when trying to transcribe
+
+**Symptom:** Claude says the audio file was not found.
+
+**Causes and fixes:**
+
+1. **Wrong path format** — Windows paths must use backslashes. In the chat, type the path with single backslashes as normal:
+   ```
+   C:\Users\Me\Downloads\recording.mp3
+   ```
+
+2. **Spaces in the path** — Paths with spaces are supported but make sure you give Claude the full path.
+
+3. **File doesn't exist** — Double-check the file is where you think it is by navigating to it in File Explorer.
+
+---
+
+## The whisper server shows as "error" or doesn't appear in Settings → Developer
+
+**Symptom:** After adding the config, the whisper server shows a red error badge or doesn't appear at all.
+
+**Fixes to try in order:**
+
+1. Make sure your JSON is valid — a single missing comma or bracket will break the entire config file. Use a JSON validator like [jsonlint.com](https://jsonlint.com) if unsure.
+
+2. Fully quit Claude Desktop (check Task Manager to make sure no Claude processes remain) and reopen it.
+
+3. Make sure Node.js is installed. Open Command Prompt and run:
+   ```
+   node --version
+   ```
+   If you get an error, download Node.js from [nodejs.org](https://nodejs.org) and install it.
+
+4. Make sure `npx` works. In Command Prompt:
+   ```
+   npx --version
+   ```
+
+---
+
+## Transcription runs but produces garbled or incorrect text
+
+**Symptom:** The transcript is mostly nonsense, repeating phrases, or in the wrong language.
+
+**Fixes:**
+
+- **Wrong language:** Add `"language": "en"` (or your language code) when asking Claude to transcribe.
+- **Poor audio quality:** Whisper works best with clear speech. Background noise, multiple overlapping speakers, or very low bitrate audio will reduce accuracy.
+- **Try a larger model:** Larger models (small, medium) are significantly more accurate than tiny or base, at the cost of speed.
+
+---
+
+## Transcription is very slow
+
+**Expected:** On CPU, a 1-hour recording takes roughly 20–60 minutes depending on the model and your processor. This is normal.
+
+**Ways to speed it up:**
+
+- Use a smaller model (`base.en` instead of `medium.en`)
+- If you only need the first portion of a recording, trim it first using VLC (**Media → Convert/Save → Edit Profile → set stop time**) or Audacity
+
+> GPU acceleration for AMD (ROCm) and NVIDIA (CUDA) on Windows may be added in a future update.
+
+---
+
+## Claude Desktop fails to install or update (HRESULT 0x80073CF9 / 0x80073CF6)
+
+**Symptom:** The Claude Desktop installer fails with an HRESULT error code.
+
+**This is a Windows MSIX packaging issue, not related to this MCP server.** Steps to resolve:
+
+1. Fully uninstall Claude Desktop via **Settings → Apps → Apps & features**
+2. Open Task Manager (**Ctrl+Shift+Esc → Details tab**) and end any remaining Claude or Cowork processes
+3. Delete the folder `C:\Users\YourUsername\AppData\Local\AnthropicClaude` if it exists
+4. **Restart your computer** — this is important; some package registrations persist in memory until reboot
+5. Run the installer again after the reboot
+
+---
+
+## Config file location
+
+If you're not sure where to find `claude_desktop_config.json`:
+
+```
+C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json
+```
+
+You can also reach it via Claude Desktop → **Settings → Developer → Edit Config**.
+
+The `AppData` folder is hidden by default. To show it in File Explorer: **View → Show → Hidden items**.
+
+---
+
+## Double backslashes in JSON — why?
+
+In JSON, the backslash `\` is an escape character. To represent a single literal backslash (as used in Windows paths), you must write `\\`. So:
+
+| Windows path | In JSON |
+|---|---|
+| `C:\whisper\Release\whisper-cli.exe` | `"C:\\whisper\\Release\\whisper-cli.exe"` |
+| `C:\Users\Me\Downloads\audio.mp3` | `"C:\\Users\\Me\\Downloads\\audio.mp3"` |
+
+This is only required inside the JSON config file. When typing paths directly into Claude in the chat, use normal single backslashes.
+
+---
+
+## Still stuck?
+
+Open an issue at [github.com/eviscerations/whisper-windows-mcp/issues](https://github.com/eviscerations/whisper-windows-mcp/issues) and include:
+
+- Your Windows version
+- The contents of your `claude_desktop_config.json` (remove any personal info)
+- The MCP server log from **Settings → Developer → View Logs**
+- What you've already tried

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * whisper-windows-mcp
+ * A Windows-native MCP server for local audio transcription using whisper.cpp
+ * https://github.com/eviscerations/whisper-windows-mcp
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+/**
+ * whisper-windows-mcp
+ * A Windows-native MCP server for local audio transcription using whisper.cpp
+ * https://github.com/eviscerations/whisper-windows-mcp
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { execFile } from "child_process";
+import { existsSync, unlinkSync } from "fs";
+import { cpus, tmpdir } from "os";
+import { join } from "path";
+import { promisify } from "util";
+const execFileAsync = promisify(execFile);
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+const WHISPER_CLI_PATH = process.env.WHISPER_CLI_PATH ?? "C:\\whisper\\Release\\whisper-cli.exe";
+const WHISPER_MODEL = process.env.WHISPER_MODEL ?? "C:\\whisper\\models\\ggml-base.en.bin";
+const FFMPEG_PATH = process.env.FFMPEG_PATH ?? "ffmpeg";
+const SYSTEM_THREADS = cpus().length;
+const DEFAULT_THREADS = Math.max(2, Math.floor(SYSTEM_THREADS / 2));
+const WHISPER_THREADS = parseInt(process.env.WHISPER_THREADS ?? String(DEFAULT_THREADS), 10);
+// Video/audio formats that need FFmpeg conversion before whisper-cli can read them
+const NEEDS_CONVERSION = [".mp4", ".mkv", ".avi", ".mov", ".webm", ".flv", ".wmv", ".m4v", ".m4a", ".ogg", ".flac"];
+const NATIVE_FORMATS = [".wav", ".mp3"];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function validatePaths() {
+    if (!existsSync(WHISPER_CLI_PATH)) {
+        return (`whisper-cli.exe not found at: ${WHISPER_CLI_PATH}\n` +
+            `Check your WHISPER_CLI_PATH environment variable in claude_desktop_config.json`);
+    }
+    if (!existsSync(WHISPER_MODEL)) {
+        return (`Whisper model not found at: ${WHISPER_MODEL}\n` +
+            `Check your WHISPER_MODEL environment variable in claude_desktop_config.json`);
+    }
+    return null;
+}
+function needsConversion(filePath) {
+    const ext = filePath.toLowerCase().slice(filePath.lastIndexOf("."));
+    return NEEDS_CONVERSION.includes(ext);
+}
+async function convertToWav(inputPath) {
+    const tmpFile = join(tmpdir(), `whisper_tmp_${Date.now()}.wav`);
+    await execFileAsync(FFMPEG_PATH, [
+        "-y", // overwrite if exists
+        "-i", inputPath,
+        "-ar", "16000", // 16kHz sample rate (whisper optimal)
+        "-ac", "1", // mono
+        "-c:a", "pcm_s16le", // 16-bit PCM WAV
+        tmpFile,
+    ], { windowsHide: true });
+    return tmpFile;
+}
+function buildArgs(filePath, model, language, outputFormat, threads) {
+    const args = [
+        "-m", model,
+        "-f", filePath,
+        "-l", language,
+        "-t", String(threads),
+    ];
+    if (outputFormat === "timestamps") {
+        // default whisper output includes timestamps
+    }
+    else if (outputFormat === "json") {
+        args.push("-oj");
+    }
+    else {
+        args.push("--no-timestamps");
+    }
+    return args;
+}
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+const server = new Server({ name: "whisper-windows-mcp", version: "1.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "transcribe_audio",
+            description: "Transcribe an audio or video file using whisper.cpp running locally on Windows. " +
+                "Natively supports mp3 and wav. " +
+                "Automatically converts video and other audio formats (mp4, mkv, avi, mov, webm, m4a, flac, ogg, etc.) " +
+                "via FFmpeg before transcription — no manual conversion needed. " +
+                "Note: long files (over 30 minutes) may take significant time and " +
+                "cannot be cancelled cleanly from Claude — use Task Manager to stop if needed.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    file_path: {
+                        type: "string",
+                        description: "Absolute Windows path to the file, e.g. C:\\Users\\You\\Downloads\\recording.mp4",
+                    },
+                    model: {
+                        type: "string",
+                        description: "Override the default model path. Leave blank to use the model configured in WHISPER_MODEL.",
+                    },
+                    language: {
+                        type: "string",
+                        description: "Language code, e.g. en, es, fr. Defaults to en.",
+                        default: "en",
+                    },
+                    output_format: {
+                        type: "string",
+                        enum: ["text", "timestamps", "json"],
+                        description: "text = plain transcript (default), timestamps = transcript with time codes, json = structured output.",
+                        default: "text",
+                    },
+                    threads: {
+                        type: "number",
+                        description: `Number of CPU threads to use. Defaults to ${WHISPER_THREADS} (half of your ${SYSTEM_THREADS} logical cores). ` +
+                            `Increase for faster processing, decrease to keep the system responsive.`,
+                    },
+                },
+                required: ["file_path"],
+            },
+        },
+        {
+            name: "check_config",
+            description: "Verify that whisper-cli.exe and the configured model file can both be found. " +
+                "Also reports thread count and FFmpeg availability. Run this first if transcription fails.",
+            inputSchema: { type: "object", properties: {} },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    // -------------------------------------------------------------------------
+    // check_config
+    // -------------------------------------------------------------------------
+    if (name === "check_config") {
+        const error = validatePaths();
+        if (error) {
+            return {
+                content: [{ type: "text", text: `❌ Configuration error:\n\n${error}` }],
+                isError: true,
+            };
+        }
+        // Check FFmpeg availability
+        let ffmpegStatus = "✅ Found";
+        try {
+            await execFileAsync(FFMPEG_PATH, ["-version"], { windowsHide: true });
+        }
+        catch {
+            ffmpegStatus = "⚠️  Not found — video/non-WAV formats will not work without FFmpeg in PATH";
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `✅ Configuration looks good!\n\n` +
+                        `whisper-cli: ${WHISPER_CLI_PATH}\n` +
+                        `Model:       ${WHISPER_MODEL}\n` +
+                        `Threads:     ${WHISPER_THREADS} of ${SYSTEM_THREADS} logical cores\n` +
+                        `FFmpeg:      ${ffmpegStatus}\n\n` +
+                        `To change thread count, add WHISPER_THREADS to your claude_desktop_config.json env block.\n` +
+                        `To use a custom FFmpeg path, add FFMPEG_PATH to the env block.`,
+                },
+            ],
+        };
+    }
+    // -------------------------------------------------------------------------
+    // transcribe_audio
+    // -------------------------------------------------------------------------
+    if (name === "transcribe_audio") {
+        const filePath = args?.file_path;
+        const model = args?.model || WHISPER_MODEL;
+        const language = args?.language || "en";
+        const outputFormat = (args?.output_format || "text");
+        const threads = Math.min(SYSTEM_THREADS, Math.max(1, Math.round(args?.threads || WHISPER_THREADS)));
+        if (!filePath) {
+            return {
+                content: [{ type: "text", text: "file_path is required." }],
+                isError: true,
+            };
+        }
+        if (!existsSync(filePath)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `File not found: ${filePath}\n\n` +
+                            `Make sure the path uses backslashes and is absolute, ` +
+                            `e.g. C:\\Users\\You\\Downloads\\audio.mp3`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const configError = validatePaths();
+        if (configError) {
+            return {
+                content: [{ type: "text", text: configError }],
+                isError: true,
+            };
+        }
+        // Convert to WAV via FFmpeg if needed
+        let transcribeFrom = filePath;
+        let tmpFile = null;
+        const converting = needsConversion(filePath);
+        if (converting) {
+            try {
+                tmpFile = await convertToWav(filePath);
+                transcribeFrom = tmpFile;
+            }
+            catch (err) {
+                const msg = err?.stderr || err?.message || String(err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `FFmpeg conversion failed:\n\n${msg}\n\n` +
+                                `Make sure FFmpeg is installed and in your system PATH.\n` +
+                                `Download from https://ffmpeg.org/download.html\n` +
+                                `Or convert to MP3 manually using VLC (Media → Convert/Save → Audio - MP3).`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        // Run whisper-cli
+        try {
+            const cliArgs = buildArgs(transcribeFrom, model, language, outputFormat, threads);
+            const { stdout, stderr } = await execFileAsync(WHISPER_CLI_PATH, cliArgs, {
+                maxBuffer: 100 * 1024 * 1024,
+                windowsHide: true,
+            });
+            const output = stdout || stderr || "(no output)";
+            const note = converting
+                ? "\n\n[Automatically converted from video/audio format via FFmpeg before transcription]"
+                : "";
+            return { content: [{ type: "text", text: output.trim() + note }] };
+        }
+        catch (err) {
+            const message = err?.stderr || err?.stdout || err?.message || String(err);
+            return {
+                content: [
+                    { type: "text", text: `Transcription failed:\n\n${message}` },
+                ],
+                isError: true,
+            };
+        }
+        finally {
+            // Always clean up temp file
+            if (tmpFile && existsSync(tmpFile)) {
+                try {
+                    unlinkSync(tmpFile);
+                }
+                catch { /* ignore cleanup errors */ }
+            }
+        }
+    }
+    return {
+        content: [{ type: "text", text: `Unknown tool: ${name}` }],
+        isError: true,
+    };
+});
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`whisper-windows-mcp v1.1.0 running | threads: ${WHISPER_THREADS}/${SYSTEM_THREADS}`);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "whisper-windows-mcp",
+  "version": "1.1.0",
+  "description": "Windows-native MCP server for local audio transcription using whisper.cpp — works with Claude Desktop on Windows",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "whisper-windows-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "whisper",
+    "whisper.cpp",
+    "transcription",
+    "speech-to-text",
+    "windows",
+    "claude",
+    "claude-desktop",
+    "model-context-protocol",
+    "audio",
+    "local"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+/**
+ * whisper-windows-mcp
+ * A Windows-native MCP server for local audio transcription using whisper.cpp
+ * https://github.com/eviscerations/whisper-windows-mcp
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { execFile } from "child_process";
+import { existsSync, unlinkSync } from "fs";
+import { cpus, tmpdir } from "os";
+import { join } from "path";
+import { promisify } from "util";
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+const WHISPER_CLI_PATH =
+  process.env.WHISPER_CLI_PATH ?? "C:\\whisper\\Release\\whisper-cli.exe";
+
+const WHISPER_MODEL =
+  process.env.WHISPER_MODEL ?? "C:\\whisper\\models\\ggml-base.en.bin";
+
+const FFMPEG_PATH =
+  process.env.FFMPEG_PATH ?? "ffmpeg";
+
+const SYSTEM_THREADS = cpus().length;
+const DEFAULT_THREADS = Math.max(2, Math.floor(SYSTEM_THREADS / 2));
+const WHISPER_THREADS = parseInt(process.env.WHISPER_THREADS ?? String(DEFAULT_THREADS), 10);
+
+// Video/audio formats that need FFmpeg conversion before whisper-cli can read them
+const NEEDS_CONVERSION = [".mp4", ".mkv", ".avi", ".mov", ".webm", ".flv", ".wmv", ".m4v", ".m4a", ".ogg", ".flac"];
+const NATIVE_FORMATS = [".wav", ".mp3"];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function validatePaths(): string | null {
+  if (!existsSync(WHISPER_CLI_PATH)) {
+    return (
+      `whisper-cli.exe not found at: ${WHISPER_CLI_PATH}\n` +
+      `Check your WHISPER_CLI_PATH environment variable in claude_desktop_config.json`
+    );
+  }
+  if (!existsSync(WHISPER_MODEL)) {
+    return (
+      `Whisper model not found at: ${WHISPER_MODEL}\n` +
+      `Check your WHISPER_MODEL environment variable in claude_desktop_config.json`
+    );
+  }
+  return null;
+}
+
+function needsConversion(filePath: string): boolean {
+  const ext = filePath.toLowerCase().slice(filePath.lastIndexOf("."));
+  return NEEDS_CONVERSION.includes(ext);
+}
+
+async function convertToWav(inputPath: string): Promise<string> {
+  const tmpFile = join(tmpdir(), `whisper_tmp_${Date.now()}.wav`);
+  await execFileAsync(FFMPEG_PATH, [
+    "-y",           // overwrite if exists
+    "-i", inputPath,
+    "-ar", "16000", // 16kHz sample rate (whisper optimal)
+    "-ac", "1",     // mono
+    "-c:a", "pcm_s16le", // 16-bit PCM WAV
+    tmpFile,
+  ], { windowsHide: true });
+  return tmpFile;
+}
+
+type OutputFormat = "text" | "timestamps" | "json";
+
+function buildArgs(
+  filePath: string,
+  model: string,
+  language: string,
+  outputFormat: OutputFormat,
+  threads: number
+): string[] {
+  const args: string[] = [
+    "-m", model,
+    "-f", filePath,
+    "-l", language,
+    "-t", String(threads),
+  ];
+
+  if (outputFormat === "timestamps") {
+    // default whisper output includes timestamps
+  } else if (outputFormat === "json") {
+    args.push("-oj");
+  } else {
+    args.push("--no-timestamps");
+  }
+
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+const server = new Server(
+  { name: "whisper-windows-mcp", version: "1.1.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "transcribe_audio",
+      description:
+        "Transcribe an audio or video file using whisper.cpp running locally on Windows. " +
+        "Natively supports mp3 and wav. " +
+        "Automatically converts video and other audio formats (mp4, mkv, avi, mov, webm, m4a, flac, ogg, etc.) " +
+        "via FFmpeg before transcription — no manual conversion needed. " +
+        "Note: long files (over 30 minutes) may take significant time and " +
+        "cannot be cancelled cleanly from Claude — use Task Manager to stop if needed.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          file_path: {
+            type: "string",
+            description:
+              "Absolute Windows path to the file, e.g. C:\\Users\\You\\Downloads\\recording.mp4",
+          },
+          model: {
+            type: "string",
+            description:
+              "Override the default model path. Leave blank to use the model configured in WHISPER_MODEL.",
+          },
+          language: {
+            type: "string",
+            description: "Language code, e.g. en, es, fr. Defaults to en.",
+            default: "en",
+          },
+          output_format: {
+            type: "string",
+            enum: ["text", "timestamps", "json"],
+            description:
+              "text = plain transcript (default), timestamps = transcript with time codes, json = structured output.",
+            default: "text",
+          },
+          threads: {
+            type: "number",
+            description:
+              `Number of CPU threads to use. Defaults to ${WHISPER_THREADS} (half of your ${SYSTEM_THREADS} logical cores). ` +
+              `Increase for faster processing, decrease to keep the system responsive.`,
+          },
+        },
+        required: ["file_path"],
+      },
+    },
+    {
+      name: "check_config",
+      description:
+        "Verify that whisper-cli.exe and the configured model file can both be found. " +
+        "Also reports thread count and FFmpeg availability. Run this first if transcription fails.",
+      inputSchema: { type: "object", properties: {} },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  // -------------------------------------------------------------------------
+  // check_config
+  // -------------------------------------------------------------------------
+  if (name === "check_config") {
+    const error = validatePaths();
+    if (error) {
+      return {
+        content: [{ type: "text", text: `❌ Configuration error:\n\n${error}` }],
+        isError: true,
+      };
+    }
+
+    // Check FFmpeg availability
+    let ffmpegStatus = "✅ Found";
+    try {
+      await execFileAsync(FFMPEG_PATH, ["-version"], { windowsHide: true });
+    } catch {
+      ffmpegStatus = "⚠️  Not found — video/non-WAV formats will not work without FFmpeg in PATH";
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            `✅ Configuration looks good!\n\n` +
+            `whisper-cli: ${WHISPER_CLI_PATH}\n` +
+            `Model:       ${WHISPER_MODEL}\n` +
+            `Threads:     ${WHISPER_THREADS} of ${SYSTEM_THREADS} logical cores\n` +
+            `FFmpeg:      ${ffmpegStatus}\n\n` +
+            `To change thread count, add WHISPER_THREADS to your claude_desktop_config.json env block.\n` +
+            `To use a custom FFmpeg path, add FFMPEG_PATH to the env block.`,
+        },
+      ],
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // transcribe_audio
+  // -------------------------------------------------------------------------
+  if (name === "transcribe_audio") {
+    const filePath = args?.file_path as string;
+    const model = (args?.model as string) || WHISPER_MODEL;
+    const language = (args?.language as string) || "en";
+    const outputFormat = ((args?.output_format as string) || "text") as OutputFormat;
+    const threads = Math.min(
+      SYSTEM_THREADS,
+      Math.max(1, Math.round((args?.threads as number) || WHISPER_THREADS))
+    );
+
+    if (!filePath) {
+      return {
+        content: [{ type: "text", text: "file_path is required." }],
+        isError: true,
+      };
+    }
+
+    if (!existsSync(filePath)) {
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              `File not found: ${filePath}\n\n` +
+              `Make sure the path uses backslashes and is absolute, ` +
+              `e.g. C:\\Users\\You\\Downloads\\audio.mp3`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const configError = validatePaths();
+    if (configError) {
+      return {
+        content: [{ type: "text", text: configError }],
+        isError: true,
+      };
+    }
+
+    // Convert to WAV via FFmpeg if needed
+    let transcribeFrom = filePath;
+    let tmpFile: string | null = null;
+    const converting = needsConversion(filePath);
+
+    if (converting) {
+      try {
+        tmpFile = await convertToWav(filePath);
+        transcribeFrom = tmpFile;
+      } catch (err: any) {
+        const msg = err?.stderr || err?.message || String(err);
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `FFmpeg conversion failed:\n\n${msg}\n\n` +
+                `Make sure FFmpeg is installed and in your system PATH.\n` +
+                `Download from https://ffmpeg.org/download.html\n` +
+                `Or convert to MP3 manually using VLC (Media → Convert/Save → Audio - MP3).`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+
+    // Run whisper-cli
+    try {
+      const cliArgs = buildArgs(transcribeFrom, model, language, outputFormat, threads);
+      const { stdout, stderr } = await execFileAsync(WHISPER_CLI_PATH, cliArgs, {
+        maxBuffer: 100 * 1024 * 1024,
+        windowsHide: true,
+      });
+
+      const output = stdout || stderr || "(no output)";
+      const note = converting
+        ? "\n\n[Automatically converted from video/audio format via FFmpeg before transcription]"
+        : "";
+
+      return { content: [{ type: "text", text: output.trim() + note }] };
+    } catch (err: any) {
+      const message = err?.stderr || err?.stdout || err?.message || String(err);
+      return {
+        content: [
+          { type: "text", text: `Transcription failed:\n\n${message}` },
+        ],
+        isError: true,
+      };
+    } finally {
+      // Always clean up temp file
+      if (tmpFile && existsSync(tmpFile)) {
+        try { unlinkSync(tmpFile); } catch { /* ignore cleanup errors */ }
+      }
+    }
+  }
+
+  return {
+    content: [{ type: "text", text: `Unknown tool: ${name}` }],
+    isError: true,
+  };
+});
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(
+    `whisper-windows-mcp v1.1.0 running | threads: ${WHISPER_THREADS}/${SYSTEM_THREADS}`
+  );
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}