Skip to main content
Glama

Deepgram Async MCP Server

by ctaylor86
GitHub
JavaScript
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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:

  1. Submit transcription job (returns immediately with request_id)

  2. Deepgram processes in background

  3. Results stored in webhook relay (Cloudflare Worker)

  4. Poll every 30 seconds until ready

  5. 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

  1. 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)

  2. 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

  3. test_deepgram_connection - Verify setup is working

Prerequisites

  1. Deepgram API key (Get one here)

  2. Webhook Relay (Cloudflare Worker) - Required!

  3. 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

  1. Push this repo to GitHub

  2. Go to Smithery

  3. Connect your GitHub repository

  4. 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:

  1. Go to Deepgram Console

  2. Navigate to API Keys

  3. Click Create a New API Key

  4. Select Member role (or Admin/Owner)

  5. 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"

  1. Verify Cloudflare Worker is deployed: wrangler deployments list

  2. Test manually: curl https://your-worker.workers.dev/health

  3. Check webhook URL in configuration is correct

"Transcript not found"

  1. Job may still be processing - wait 30s and try again

  2. Check request_id is correct

  3. Transcripts expire after 7 days in webhook relay

"403 Forbidden"

  1. API key lacks permissions - must be Member role or higher

  2. See API_PERMISSIONS.md for detailed guide

"Failed to submit transcription job"

  1. Verify audio URL is publicly accessible

  2. Check Deepgram account has credits

  3. Ensure file format is supported (MP3, WAV, MP4, etc.)

Complete 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)

Cloudflare (Free Tier)

  • 100,000 requests/day

  • 1 GB KV storage

  • More than enough for most use cases

Smithery (Free Tier)

Support

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:

  1. TypeScript compiles without errors

  2. Smithery build succeeds

  3. 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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

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.

  1. Why This Server?
    1. Architecture
      1. Features
        1. Two MCP Tools
      2. Prerequisites
        1. Quick Start
          1. Step 1: Deploy Webhook Relay
          2. Step 2: Deploy MCP Server to Smithery
          3. Step 3: Configure
          4. Step 4: Use in Claude
        2. Configuration
          1. Required
          2. Optional
        3. API Key Requirements
          1. Usage Examples
            1. Basic Transcription
            2. Marketing Use Case (Full Features)
            3. Check Status
          2. Processing Times
            1. Troubleshooting
              1. "Webhook relay unreachable"
              2. "Transcript not found"
              3. "403 Forbidden"
              4. "Failed to submit transcription job"
            2. Complete Documentation
              1. Project Structure
                1. Costs
                  1. Deepgram (Pay-as-you-go)
                  2. Cloudflare (Free Tier)
                  3. Smithery (Free Tier)
                2. Support
                  1. Related Projects
                    1. License
                      1. Contributing
                        1. Changelog
                          1. v2.0.0 (Current)
                          2. v1.0.0

                        New MCP Servers

                        MCP directory API

                        We provide all the information about MCP servers via our MCP API.

                        curl -X GET 'https://glama.ai/api/mcp/v1/servers/ctaylor86/deepgram-mcp-server'

                        If you have feedback or need assistance with the MCP directory API, please join our Discord server