io.github.jwulff/whisper-mcp

Whisper MCP Server

A lightweight MCP (Model Context Protocol) server for local audio transcription using whisper.cpp. There are several Whisper MCP implementations out there. This one is minimal and pairs with apple-voice-memo-mcp for a complete voice memo workflow.

Features

• Local transcription - All processing happens on your machine
• Multiple models - Choose from tiny, base, small, medium, or large models
• Various formats - Supports wav, mp3, m4a, and other audio formats
• Timestamps - Get transcriptions with or without timestamps

Requirements

• macOS (tested on Apple Silicon)
• Node.js 18+
• whisper-cpp: brew install whisper-cpp
• ffmpeg: brew install ffmpeg

Installation

npm install -g whisper-mcp

Or run directly:

npx whisper-mcp

Configuration

Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "whisper-mcp": {
      "command": "npx",
      "args": ["-y", "whisper-mcp"]
    }
  }
}

After editing, restart Claude Desktop.

Claude Code (CLI)

For Claude Code, add to your project's .mcp.json file:

{
  "mcpServers": {
    "whisper-mcp": {
      "command": "npx",
      "args": ["-y", "whisper-mcp"]
    }
  }
}

Or for user-wide configuration, add to ~/.claude/settings.json:

{
  "mcpServers": {
    "whisper-mcp": {
      "command": "npx",
      "args": ["-y", "whisper-mcp"]
    }
  }
}

Tip: Use /mcp in Claude Code to verify the server is connected.

Local Development Setup

If running from source instead of npm:

{
  "mcpServers": {
    "whisper-mcp": {
      "command": "node",
      "args": ["/path/to/whisper-mcp/dist/index.js"]
    }
  }
}

With Apple Voice Memos MCP

For a complete voice memo workflow, use alongside apple-voice-memo-mcp:

{
  "mcpServers": {
    "apple-voice-memo-mcp": {
      "command": "npx",
      "args": ["-y", "apple-voice-memo-mcp"]
    },
    "whisper-mcp": {
      "command": "npx",
      "args": ["-y", "whisper-mcp"]
    }
  }
}

MCP Tools

transcribe_audio

Transcribe an audio file using Whisper.

Parameters:

• file_path (required): Absolute path to the audio file
• model (optional): Model to use (tiny.en, base.en, small.en, medium.en, large). Default: base.en
• language (optional): Language code. Default: en
• output_format (optional): text, timestamps, or json. Default: text

Example:

{
  "file_path": "/path/to/audio.m4a",
  "model": "medium.en",
  "output_format": "timestamps"
}

list_whisper_models

List available Whisper models and their download status.

Returns:

{
  "models": [
    {
      "name": "base.en",
      "size": "142 MB",
      "downloaded": true,
      "path": "/Users/you/.whisper/ggml-base.en.bin"
    }
  ]
}

download_whisper_model

Download a Whisper model for local use.

Parameters:

• model (required): Model to download (tiny.en, base.en, small.en, medium.en, large)

Models

Models are stored in ~/.whisper/.

Workflow Example

1. List your voice memos: list_voice_memos
2. Get audio path: get_audio with memo ID
3. Transcribe: transcribe_audio with the file path
4. Save to your vault

Development

# Clone and install
git clone https://github.com/jwulff/whisper-mcp.git
cd whisper-mcp
npm install

# Build
npm run build

# Test with MCP inspector
npm run inspector

License

MIT