Deepgram Async MCP Server
Remote MCP server for Deepgram Async Speech-to-Text API with webhook relay support. Transcribe long audio and video files asynchronously - perfect for marketers transcribing hour-long videos and podcasts without timeout issues.
Why This Server?
Problem: Claude MCP Connect has a 10-second timeout, but long videos take minutes to transcribe.
Solution: True async processing with polling:
- Submit transcription job (returns immediately with request_id)
- Deepgram processes in background
- Results stored in webhook relay (Cloudflare Worker)
- Poll every 30 seconds until ready
- Get full transcript with all features
Architecture
Your AI → MCP Server → Deepgram API (async)
↓
Webhook Relay (Cloudflare Worker + KV Storage)
↑
MCP Server ← Poll for results
Features
Two MCP Tools
-
submit_transcription_job - Send audio/video URLs for async transcription
- ✅ Handles 1-hour+ videos without timeout
- ✅ Speaker diarization (detect different speakers)
- ✅ Smart formatting and punctuation
- ✅ Sentiment analysis
- ✅ Topic detection
- ✅ Entity extraction (names, places, brands)
- ✅ Summarization
- ✅ Multi-language support
- ✅ Multiple AI models (Nova-3, Nova-2, Whisper)
-
check_job_status - Retrieve transcription results when ready
- ✅ Poll for job completion
- ✅ Get full transcription with all requested features
- ✅ Automatic fallback to Deepgram Management API
-
test_deepgram_connection - Verify setup is working
Prerequisites
- Deepgram API key (Get one here)
- Webhook Relay (Cloudflare Worker) - Required!
- Smithery account for deployment
Quick Start
Step 1: Deploy Webhook Relay
See the complete guide: SETUP_GUIDE.md
Quick version:
cd deepgram-webhook-relay
npm install -g wrangler
wrangler login
wrangler kv:namespace create TRANSCRIPTS
# Update wrangler.toml with KV namespace ID
wrangler deploy
You'll get a URL like: https://deepgram-webhook-relay.YOUR_SUBDOMAIN.workers.dev
Step 2: Deploy MCP Server to Smithery
- Push this repo to GitHub
- Go to Smithery
- Connect your GitHub repository
- Smithery will auto-deploy
Step 3: Configure
Provide these values in Smithery:
{
"deepgramApiKey": "your-deepgram-api-key",
"webhookUrl": "https://your-worker.workers.dev/callback"
}
Step 4: Use in Claude
System Prompt:
When transcribing audio/video:
1. Use submit_transcription_job to start
2. Get the request_id from response
3. Wait 30 seconds (use sleep tool)
4. Use check_job_status with request_id
5. If "Still Processing", repeat steps 3-4
6. When "Complete", present the transcript
Example:
User: Transcribe this podcast: https://example.com/podcast.mp4
AI: I'll transcribe that for you.
[Uses submit_transcription_job]
Job submitted! Request ID: abc123
[Waits 30s]
[Uses check_job_status]
Still processing...
[Waits 30s]
[Uses check_job_status]
✅ Complete! Here's the transcript: ...
Configuration
Required
- deepgramApiKey: Your Deepgram API key (must have Member role or higher)
- webhookUrl: Your Cloudflare Worker callback URL (e.g.,
https://your-worker.workers.dev/callback)
Optional
- projectId: Your Deepgram project ID (auto-detected if not provided)
API Key Requirements
⚠️ Important: Your Deepgram API key must have Member role or higher.
Required permissions:
project:write- Submit transcription jobsproject:read- Auto-detect project ID (optional if you provide projectId)usage:read- Check job status via Management API
How to create a proper API key:
- Go to Deepgram Console
- Navigate to API Keys
- Click Create a New API Key
- Select Member role (or Admin/Owner)
- Copy the key and use it in your configuration
See API_PERMISSIONS.md for detailed troubleshooting.
Usage Examples
Basic Transcription
Tool: submit_transcription_job
Parameters:
url: "https://example.com/video.mp4"
smart_format: true
punctuate: true
Marketing Use Case (Full Features)
Tool: submit_transcription_job
Parameters:
url: "https://example.com/podcast.mp4"
diarize: true # Detect speakers
smart_format: true # Professional formatting
punctuate: true # Add punctuation
paragraphs: true # Split into paragraphs
sentiment: true # Analyze sentiment
topics: true # Detect topics
detect_entities: true # Extract names, brands
summarize: true # Generate summary
model: "nova-3" # Latest model
Check Status
Tool: check_job_status
Parameters:
request_id: "abc123-def456-..."
Processing Times
Typical processing times (varies by file length and complexity):
- 5-minute video: 30-60 seconds
- 30-minute video: 1-2 minutes
- 1-hour video: 2-3 minutes
- 2-hour podcast: 5-8 minutes
Recommendation: Poll every 30 seconds to balance responsiveness and API usage.
Troubleshooting
"Webhook relay unreachable"
- Verify Cloudflare Worker is deployed:
wrangler deployments list - Test manually:
curl https://your-worker.workers.dev/health - Check webhook URL in configuration is correct
"Transcript not found"
- Job may still be processing - wait 30s and try again
- Check request_id is correct
- Transcripts expire after 7 days in webhook relay
"403 Forbidden"
- API key lacks permissions - must be Member role or higher
- See API_PERMISSIONS.md for detailed guide
"Failed to submit transcription job"
- Verify audio URL is publicly accessible
- Check Deepgram account has credits
- Ensure file format is supported (MP3, WAV, MP4, etc.)
Complete Documentation
- SETUP_GUIDE.md - Step-by-step deployment guide
- API_PERMISSIONS.md - API key permissions and troubleshooting
- DEPLOYMENT.md - Smithery deployment details
- deepgram-webhook-relay/README.md - Webhook relay documentation
Project Structure
deepgram-mcp-server/ # MCP server (this directory)
├── src/
│ ├── index.ts # Main MCP server
│ └── deepgram-client.ts # Deepgram API client
├── package.json
├── smithery.yaml
└── README.md
deepgram-webhook-relay/ # Cloudflare Worker
├── worker.js # Webhook relay logic
├── wrangler.toml # Cloudflare config
└── README.md
Costs
Deepgram (Pay-as-you-go)
- Nova-3: $0.0043/minute
- 1-hour video = ~$0.26
- Pricing details
Cloudflare (Free Tier)
- 100,000 requests/day
- 1 GB KV storage
- More than enough for most use cases
Smithery (Free Tier)
- Generous free tier for MCP servers
- Pricing details
Support
- Setup Issues: See SETUP_GUIDE.md
- API Permissions: See API_PERMISSIONS.md
- Deepgram: https://developers.deepgram.com
- Smithery: https://smithery.ai/docs
Related Projects
This MCP server works with other async tools:
- Klap (video editing)
- Rendi (video rendering)
- Any service with async processing + callbacks
License
MIT
Contributing
Pull requests welcome! Please ensure:
- TypeScript compiles without errors
- Smithery build succeeds
- Documentation is updated
Changelog
v2.0.0 (Current)
- ✅ True async processing with webhook relay
- ✅ Cloudflare Worker for transcript storage
- ✅ Polling support for long videos
- ✅ Handles 1-hour+ content without timeout
v1.0.0
- Initial release with basic async support