audio-transcription-mcp
Provides real-time audio transcription using OpenAI's Whisper API, enabling AI agents to capture and transcribe system audio for meetings, videos, and more.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@audio-transcription-mcp Start transcribing my meeting audio"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Audio Transcription MCP Server
Real-time audio transcription using OpenAI Whisper. Capture and transcribe system audio (meetings, videos, music) automatically with AI assistance through Cursor or Claude Desktop.
β¨ Features
π€ Real-time transcription - Captures and transcribes audio as it plays
π Zero installation - Use with
npx, no global install neededπ€ AI-powered - Uses OpenAI's Whisper API for accurate transcription
π Timestamped transcripts - Every entry is timestamped in markdown format
π Session isolation - Each session gets its own unique transcript file
β‘ Smart silence detection - Automatically pauses when no audio detected
π― Automated setup - One command sets up audio routing
π§ͺ Built-in testing - Verify your setup before starting
Related MCP server: audio-mcp
π Quick Start (5 Minutes)
Step 1: Run Automated Setup
The setup script installs everything you need and guides you through configuration:
npx audio-transcription-mcp setupWhat this does:
β Installs Homebrew (if needed)
β Installs ffmpeg for audio processing
β Installs BlackHole virtual audio driver
β Guides you through creating a Multi-Output Device (or does it automatically!)
β Takes 5 minutes, mostly automated
First time? The script will walk you through everything with clear instructions. Don't worry if it asks for your Mac password - that's normal for installing software!
Step 2: Test Your Setup
Verify everything works before using it:
npx audio-transcription-mcp testThis captures 5 seconds of audio and shows you if it's working correctly.
Step 3: Configure Your AI Assistant
Add to your Cursor or Claude Desktop config:
Edit ~/.cursor/config.json:
{
"mcpServers": {
"audio-transcription": {
"command": "npx",
"args": ["-y", "audio-transcription-mcp"],
"env": {
"OPENAI_API_KEY": "sk-your-key-here",
"INPUT_DEVICE_NAME": "BlackHole"
}
}
}
}Then restart Cursor and ask:
"Start transcribing audio"
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"audio-transcription": {
"command": "npx",
"args": ["-y", "audio-transcription-mcp"],
"env": {
"OPENAI_API_KEY": "sk-your-key-here",
"INPUT_DEVICE_NAME": "BlackHole",
"OUTFILE_DIR": "/Users/yourname/Documents/Transcripts"
},
"allowedDirectories": [
"/Users/yourname/Documents/Transcripts"
]
}
}
}Important:
Create the directory:
mkdir -p ~/Documents/TranscriptsReplace
yournamewith your actual usernameRestart Claude Desktop
Then ask:
"Start transcribing audio"
Step 4: Set System Output
Go to System Settings > Sound > Output and select "Multi-Output Device"
This routes audio to both your speakers (so you can hear) and BlackHole (for transcription).
Step 5: Start Transcribing!
In Cursor or Claude Desktop, just ask:
"Start transcribing audio"
Your AI assistant will start capturing and transcribing audio in real-time!
π What You Need
macOS 10.15+ (Catalina or later)
OpenAI API key - Get one here (pay-as-you-go, ~$0.36/hour - see detailed costs)
5 minutes for setup
π― Use Cases
Meeting transcription - Zoom, Google Meet, Teams calls
Content creation - Transcribe videos, podcasts, or music
Accessibility - Real-time captions for any audio
Note-taking - Automatic transcripts of lectures or presentations
Research - Transcribe interviews or focus groups
π§ Troubleshooting
Audio Not Being Captured
Problem: Test shows silent or very low audio levels
Solution:
Check System Settings > Sound > Output is set to "Multi-Output Device"
Open Audio MIDI Setup and verify both outputs are checked:
β Built-in Output
β BlackHole 2ch
Play some audio and run
npx audio-transcription-mcp testagain
BlackHole Not Showing Up
Problem: BlackHole doesn't appear in device list
Solution: Restart your Mac. Audio drivers require a restart to be recognized by the system.
Setup Script Fails
Problem: Automated setup doesn't work
Solution: The script will fall back to manual mode with clear instructions. This is normal on first run if accessibility permissions aren't granted. Just follow the 4-step guide shown.
Want to Start Over?
If you need to remove everything and start fresh:
# Uninstall BlackHole and ffmpeg
brew uninstall blackhole-2ch ffmpeg
# Delete Multi-Output Device
# 1. Open Audio MIDI Setup
# 2. Select "Multi-Output Device" in left sidebar
# 3. Press Delete key
# Then run setup again
npx audio-transcription-mcp setupNeed More Help?
π Detailed Setup Guide
π Report an Issue
π¬ Discussions
π Additional Documentation
π οΈ Advanced Usage
Standalone CLI Mode
You can use this as a standalone CLI without MCP:
# Start transcription (saves to meeting_transcript.md)
npx audio-transcription-mcp start
# Press Ctrl+C to stopConfigure via .env file:
OPENAI_API_KEY=sk-your-key-here
INPUT_DEVICE_NAME=BlackHole
CHUNK_SECONDS=8
OUTFILE=meeting_transcript.mdMCP Server Tools
When used with Cursor or Claude Desktop, these tools are available:
start_transcription- Start capturing and transcribing audiopause_transcription- Pause transcription temporarilyresume_transcription- Resume after pausestop_transcription- Stop and get session statsget_status- Check if transcription is runningget_transcript- Retrieve current transcript contentclear_transcript- Clear and start freshcleanup_transcript- Delete transcript file
Configuration Options
Environment variables you can customize:
Variable | Default | Description |
| (required) | Your OpenAI API key |
|
| Audio input device name |
|
| Seconds of audio per chunk |
|
| OpenAI Whisper model |
|
| Output directory for transcripts |
|
| Audio sample rate (Hz) |
|
| Number of audio channels |
ποΈ How It Works
Audio Routing: Multi-Output Device sends system audio to both your speakers and BlackHole
Capture: ffmpeg captures audio from BlackHole in 8-second chunks
Processing: Audio is converted to WAV format suitable for Whisper API
Transcription: Each chunk is sent to OpenAI Whisper for transcription
Output: Timestamped text is appended to a markdown file in real-time
Silence Detection: Automatically pauses after 32 seconds of silence to save API costs
π° Costs & Performance
What You're Paying For
You ONLY pay for OpenAI Whisper API calls - everything else runs locally for free!
β FREE (runs locally on your machine):
Audio capture with ffmpeg
Audio processing and buffer management
Silence detection and level analysis
File operations (writing/reading transcripts)
All MCP server operations
π° PAID (OpenAI API):
Only the transcription API calls to OpenAI Whisper
$0.006 per minute of audio transcribed
Silent chunks are automatically skipped to save money
Actual Costs
With default 8-second chunks:
Duration | API Calls | Approximate Cost |
1 minute | ~7.5 chunks | $0.006 |
1 hour | ~450 chunks | $0.36 |
8-hour workday | ~3,600 chunks | $2.88 |
Cost per chunk: ~$0.0008 (less than a tenth of a cent!)
Built-in Cost Savings
The tool includes smart silence detection that saves you money:
π Silent audio chunks are NEVER sent to OpenAI
π° Automatically tracks cost savings in the debug log
βΈοΈ Auto-pauses after 32 seconds of silence
π View statistics with
get_statusto see chunks skipped
Example: In a 1-hour meeting with 15 minutes of silence, you save ~$0.09 automatically!
Performance
Memory usage: 50-100 MB per session
CPU usage: Minimal (ffmpeg handles audio processing)
API latency: 1-3 seconds per chunk
Accuracy: 90-95% for clear speech
Network: Only during transcription API calls
Cost Optimization Tips
Increase chunk size - Fewer API calls (set
CHUNK_SECONDS=15)Use silence detection - Enabled by default, saves money automatically
Pause when not needed - Use
pause_transcriptionduring breaksMonitor usage - Check OpenAI dashboard for actual costs
Bottom line: Transcription is cheap (~36Β’/hour), runs mostly locally, and automatically saves money by skipping silence. You're only charged when actual speech is being transcribed.
π§ͺ Development & Testing
For contributors and developers:
π See MCP_SETUP.md for complete setup instructions
Just add to your config and restart - that's it!
See the npx configuration at the top of this README for Cursor and Claude Desktop.
For Standalone CLI (Local Development)
π See GETTING_STARTED.md for complete setup instructions
# Install dependencies
npm install
npm run build
# Configure environment
cp env.example .env # Then add your OpenAI API key
# Run standalone CLI
npm startπ License & Contributing
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.
Development Resources
π MCP Setup Guide
π§ Installation Guide
Made with β€οΈ for transcribing meetings, content, and conversations.
Star β this repo if you find it useful!
Available Tools
8 toolscleanup_transcriptA
Delete the transcript file completely. Use this to remove the transcript file when you're done.
Inputs: no named parameters.
clear_transcriptA
Clear the transcript file and reinitialize it with a fresh header.
Inputs: no named parameters.
get_statusA
Get the current status of the transcription session including whether it's running, number of chunks processed, errors, and session duration. CRITICAL: AI assistants should check this regularly (every 30-60 seconds) during active transcription to: 1) Catch audio routing issues or silence detection, 2) Monitor session duration and alert user if running 30+ minutes (prevents forgotten recordings and excessive API costs), 3) Detect paused states and warnings. The status.warning field will contain important alerts that should be shown to the user immediately.
Inputs: no named parameters.
get_transcriptA
Retrieve the current transcript content. Optionally get only the last N lines.
Inputs: lines.
pause_transcriptionA
Pause the current transcription session. Audio capture continues but transcription is paused. Use resume_transcription to continue.
Inputs: no named parameters.
resume_transcriptionA
Resume transcription after it has been paused (either manually or due to silence detection).
Inputs: no named parameters.
start_transcriptionA
Start capturing and transcribing system audio in real-time using OpenAI Whisper. Audio is captured in chunks and transcribed continuously. IMPORTANT: After starting, periodically check get_status (every 30-60 seconds) to monitor for issues. SAFETY FEATURES: The system will auto-pause in two scenarios: 1) After 32 seconds of silence, 2) After 30 minutes of NO user interaction (prevents forgotten recordings). User interaction = calling get_status, pause_transcription, resume_transcription, get_transcript, or clear_transcript. When paused, you'll see isPaused: true in status. User must explicitly call resume_transcription to continue.
Inputs: outputFile, inputDevice, chunkSeconds.
stop_transcriptionA
Stop the current transcription session completely and return statistics. This ends the session and stops audio capture.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 8 tools
Each tool targets a distinct action in the transcription lifecycle: start, pause, resume, stop, status check, transcript retrieval, clearing, and deleting. No two tools overlap in purpose, even pause vs. stop and clear vs. cleanup are clearly differentiated by their descriptions.
All tool names follow a consistent verb_noun pattern using snake_case: start_transcription, pause_transcription, get_status, etc. The naming is uniform and predictable, making it easy to infer the function of each tool.
With 8 tools, the set is well-scoped for an audio transcription server. Each tool covers a necessary part of the session lifecycle without redundancy or bloat, fitting comfortably within the ideal range.
The tool set provides full lifecycle coverage: start, manage (pause/resume), monitor (status), retrieve output, and clean up (clear/delete). There are no obvious dead ends or missing operations for the stated purpose.
Maintenance
Related MCP Connectors
Transcribe audio and video and work with your transcript library from any AI app. 119 languages.
Transcribe audio, video and YouTube links, then search, summarize and export your transcripts.
Screen recording, meeting notes, and voice dictation - all with AI
Audio, video and podcast feeds to text with Whisper. Timestamps, SRT/VTT, 99 languages. Per minute.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAI-powered voice transcription app for macOS using WhisperKit168MIT
- AlicenseNot gradedqualityDmaintenanceLocal MCP server for macOS that captures microphone input and/or system audio output into explicit, user-defined sessions and exposes the raw WAV audio to AI agents through MCP tools.7MIT
- AlicenseNot gradedqualityCmaintenanceLocal-first meeting capture and transcription for Claude Code. Records audio from meeting apps, transcribes locally with whisper.cpp, and produces structured notes via Claude.1Apache 2.0
- AlicenseAqualityDmaintenanceEnables voice input for AI coding assistants by recording audio, transcribing it locally with Whisper, and optionally typing the text at the cursor position. Supports multiple languages and works with MCP-compatible tools like OpenCode, Claude Code, and Cursor.319 npm1MIT