AssemblyAI MCP Server

A Model Context Protocol (MCP) server that provides access to AssemblyAI's transcription services. This server enables AI assistants to transcribe audio files and manage transcription jobs through a standardized interface.

Vibe Code Spectrum

On a scale of 1 to 10, 10 being the most vibey, this is a 9.

Features

• Audio transcription from URLs and local files

• Asynchronous job submission for large files

• Transcript retrieval and status checking

• Resource access to transcript data

• Type-safe implementation with Zod validation

• Error handling and graceful shutdown

Installation

1. Clone or create this project directory

2. Install dependencies:

   npm install

3. Set up your AssemblyAI API key (see Configuration section)

4. Build the TypeScript code:

   npm run build

Configuration

You need an AssemblyAI API key to use this server. Get one from AssemblyAI.

Set the environment variable:

Or create a .env file:

Usage

Running the Server

You can run the AssemblyAI MCP server in several ways:

Direct execution with npx/pnpm dlx (recommended)

Adding to Claude Code

Local development

Start the MCP server:

For development with auto-rebuild:

MCP Tools

The server provides the following tools:

transcribe_url

Transcribe audio from a remote URL and wait for completion.

Parameters:

• audioUrl (string, required): URL of the audio file

• options (object, optional): Transcription options

  • speaker_labels (boolean): Enable speaker diarization

  • language_code (string): Specify language (e.g., "en")

  • punctuate (boolean): Add punctuation

  • format_text (boolean): Format text for readability

Example:

transcribe_file

Transcribe audio from a local file path and wait for completion.

Parameters:

• filePath (string, required): Local path to the audio file

• options (object, optional): Same as transcribe_url

Example:

submit_transcription

Submit audio for transcription without waiting for completion. Returns immediately with a job ID.

Parameters:

• audio (string, required): URL or local file path

• options (object, optional): Same transcription options

Example:

get_transcript

Retrieve the status and results of a transcription job.

Parameters:

• transcriptId (string, required): The transcript ID returned from previous calls

Example:

MCP Resources

transcript://{id}

Access transcript data directly by ID. Provides structured JSON with all transcript information.

Example URI: transcript://1234567890

Returns:

Integration Examples

With Claude Desktop

Add to your claude_desktop_config.json:

With Other MCP Clients

The server uses stdio transport, so it's compatible with any MCP client that supports this transport method.

Workflow Examples

Quick Transcription

1. Use transcribe_url or transcribe_file for immediate results

2. The tool waits for completion and returns the full transcript

Async Processing

1. Use submit_transcription for large files

2. Use get_transcript to check status and retrieve results

3. Use the transcript:// resource for structured data access

Speaker Identification

Error Handling

The server provides detailed error messages for common issues:

• Missing API key: Server won't start without ASSEMBLYAI_API_KEY

• Invalid audio URLs: Clear error messages for inaccessible files

• File not found: Helpful messages for local file issues

• API errors: AssemblyAI error messages passed through

• Invalid transcript IDs: Clear feedback for non-existent transcripts

Development

Building

Development Mode

Watch Mode

Requirements

• Node.js 18.0.0 or higher

• AssemblyAI API key

• MCP-compatible client

License

MIT License

Support

For AssemblyAI API issues, visit AssemblyAI Documentation. For MCP protocol questions, see Model Context Protocol.