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```bash
npm install -g whisper-mcp
Or run directly:```bash
npx whisper-mcp
Configuration
Claude Desktop
Add to your Claude Desktop config file:
macOS: `~/Library/Application Support/Claude/claude_desktop_config.json````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:```json
{
"mcpServers": {
"whisper-mcp": {
"command": "npx",
"args": ["-y", "whisper-mcp"]
}
}
}
Or for user-wide configuration, add to ~/.claude/settings.json:```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:```json
{
"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:```json
{
"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:**```json
{
"file_path": "/path/to/audio.m4a",
"model": "medium.en",
"output_format": "timestamps"
}
list_whisper_models
List available Whisper models and their download status.
Returns:```json
{
"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
| Model | Size | Speed | Quality |
|-------|------|-------|---------|
| tiny.en | 75 MB | Fastest | Basic |
| base.en | 142 MB | Fast | Good |
| small.en | 466 MB | Medium | Better |
| medium.en | 1.5 GB | Slow | Great |
| large | 2.9 GB | Slowest | Best |
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```bash
# 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