MCP 服务器

Deepgram Async MCP Server

Enables asynchronous transcription of long audio and video files using Deepgram's Speech-to-Text API with features like speaker diarization, sentiment analysis, topic detection, and summarization without timeout issues.

README

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 jobs
project: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