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

Clone or create this project directory
Install dependencies:
```
npm install
```
Set up your AssemblyAI API key (see Configuration section)
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:

export ASSEMBLYAI_API_KEY="your-api-key-here"

Or create a .env file:

ASSEMBLYAI_API_KEY=your-api-key-here

Usage

Running the Server

You can run the AssemblyAI MCP server in several ways:

Direct execution with npx/pnpm dlx (recommended)

# Using npx
npx assembly-ai-mcp@latest

# Using pnpm dlx
pnpm dlx assembly-ai-mcp@latest

Adding to Claude Code

claude mcp add assembly-ai-mcp --scope user -- pnpm dlx assembly-ai-mcp@latest

Local development

Start the MCP server:

npm start

For development with auto-rebuild:

npm run watch

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:

{
  "audioUrl": "https://example.com/audio.mp3",
  "options": {
    "speaker_labels": true,
    "punctuate": true
  }
}

`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:

{
  "filePath": "/path/to/audio.wav",
  "options": {
    "language_code": "en"
  }
}

`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:

{
  "audio": "https://example.com/large-audio.mp3",
  "options": {
    "speaker_labels": true
  }
}

`get_transcript`

Retrieve the status and results of a transcription job.

Parameters:

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

Example:

{
  "transcriptId": "1234567890"
}

MCP Resources

`transcript://{id}`

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

Example URI: transcript://1234567890

Returns:

{
  "id": "1234567890",
  "status": "completed",
  "text": "Hello, this is a test transcription...",
  "confidence": 0.95,
  "words": [...],
  "utterances": [...],
  "created": "2024-01-01T00:00:00Z",
  "completed": "2024-01-01T00:01:30Z"
}

Integration Examples

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "assemblyai": {
      "command": "node",
      "args": ["/path/to/assemblyai-mcp-server/dist/index.js"],
      "env": {
        "ASSEMBLYAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

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

Use transcribe_url or transcribe_file for immediate results
The tool waits for completion and returns the full transcript

Async Processing

Use submit_transcription for large files
Use get_transcript to check status and retrieve results
Use the transcript:// resource for structured data access

Speaker Identification

{
  "audioUrl": "https://example.com/meeting.mp3",
  "options": {
    "speaker_labels": true,
    "punctuate": true,
    "format_text": true
  }
}

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

npm run build

Development Mode

npm run dev

Watch Mode

npm run watch

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.

AssemblyAI MCP Server

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

Clone or create this project directory
Install dependencies:
```
npm install
```
Set up your AssemblyAI API key (see Configuration section)
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:

export ASSEMBLYAI_API_KEY="your-api-key-here"

Or create a .env file:

ASSEMBLYAI_API_KEY=your-api-key-here

Usage

Running the Server

You can run the AssemblyAI MCP server in several ways:

Direct execution with npx/pnpm dlx (recommended)

# Using npx
npx assembly-ai-mcp@latest

# Using pnpm dlx
pnpm dlx assembly-ai-mcp@latest

Adding to Claude Code

claude mcp add assembly-ai-mcp --scope user -- pnpm dlx assembly-ai-mcp@latest

Local development

Start the MCP server:

npm start

For development with auto-rebuild:

npm run watch

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:

{
  "audioUrl": "https://example.com/audio.mp3",
  "options": {
    "speaker_labels": true,
    "punctuate": true
  }
}

`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:

{
  "filePath": "/path/to/audio.wav",
  "options": {
    "language_code": "en"
  }
}

`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:

{
  "audio": "https://example.com/large-audio.mp3",
  "options": {
    "speaker_labels": true
  }
}

`get_transcript`

Retrieve the status and results of a transcription job.

Parameters:

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

Example:

{
  "transcriptId": "1234567890"
}

MCP Resources

`transcript://{id}`

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

Example URI: transcript://1234567890

Returns:

{
  "id": "1234567890",
  "status": "completed",
  "text": "Hello, this is a test transcription...",
  "confidence": 0.95,
  "words": [...],
  "utterances": [...],
  "created": "2024-01-01T00:00:00Z",
  "completed": "2024-01-01T00:01:30Z"
}

Integration Examples

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "assemblyai": {
      "command": "node",
      "args": ["/path/to/assemblyai-mcp-server/dist/index.js"],
      "env": {
        "ASSEMBLYAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

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

Use transcribe_url or transcribe_file for immediate results
The tool waits for completion and returns the full transcript

Async Processing

Use submit_transcription for large files
Use get_transcript to check status and retrieve results
Use the transcript:// resource for structured data access

Speaker Identification

{
  "audioUrl": "https://example.com/meeting.mp3",
  "options": {
    "speaker_labels": true,
    "punctuate": true,
    "format_text": true
  }
}

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

npm run build

Development Mode

npm run dev

Watch Mode

npm run watch

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.