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, local files, and base64 data
• Chat attachment support for TypingMind and similar environments
• Automatic file upload to AssemblyAI for local files
• Base64 and URL handling for chat-attached audio files
• Asynchronous job submission for large files
• Transcript retrieval and status checking
• Resource access to transcript data
• Flexible API key configuration (direct or from file)
• EU instance support via custom base URL
• Type-safe implementation with Zod validation
• Error handling and graceful shutdown

Installation

From npm (recommended)

npm install -g @unboundai/assembly-ai-mcp

Or use directly with npx/pnpm dlx (see Usage section).

From source

1. Clone this repository
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.

Environment Variables

Required (one of the following):

• ASSEMBLYAI_API_KEY - Your AssemblyAI API key directly
• ASSEMBLYAI_API_KEY_FILE - Path to a file containing your API key

Optional:

• ASSEMBLYAI_BASE_URL - Custom base URL for AssemblyAI API (e.g., for EU instance)

Configuration Examples

Option 1: Direct API Key

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

Option 2: API Key from File

export ASSEMBLYAI_API_KEY_FILE="/path/to/api-key.txt"

Option 3: EU Instance

export ASSEMBLYAI_API_KEY="your-api-key-here"
export ASSEMBLYAI_BASE_URL="https://api.assemblyai.eu"

Using .env file:

ASSEMBLYAI_API_KEY=your-api-key-here
# Or use a file path:
# ASSEMBLYAI_API_KEY_FILE=/path/to/api-key.txt

# Optional: Use EU instance
# ASSEMBLYAI_BASE_URL=https://api.assemblyai.eu

Usage

Running the Server

You can run the AssemblyAI MCP server in several ways:

Direct execution with npx/pnpm dlx (recommended)

# Using npx
npx @unboundai/assembly-ai-mcp@latest

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

Adding to Claude Code

claude mcp add assembly-ai-mcp --scope user -- pnpm dlx @unboundai/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
  }
}

upload_file

Upload a local audio file to AssemblyAI and get the upload URL. Use this if you want to upload a file once and transcribe it multiple times.

Parameters:

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

Example:

{
  "filePath": "/path/to/audio.wav"
}

upload_from_data

Upload audio from base64 encoded data or a URL (e.g., from chat attachments in TypingMind). Returns upload URL for transcription.

Parameters:

• data (string, required): Base64 encoded audio data or URL to the audio file
• filename (string, optional): Filename with extension (e.g., 'audio.mp3'). Required for base64 data to determine format.

Examples:

{
  "data": "https://example.com/temp/audio.mp3"
}

{
  "data": "data:audio/mp3;base64,//uQx...",
  "filename": "recording.mp3"
}

transcribe_file

Upload and transcribe audio from a local file path. The file is automatically uploaded to AssemblyAI before transcription. Waits 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"
  }
}

transcribe_from_data

Upload and transcribe audio from base64 encoded data or URL (e.g., from chat attachments). Perfect for TypingMind and other chat environments. Waits for completion.

Parameters:

• data (string, required): Base64 encoded audio data or URL to the audio file
• filename (string, optional): Filename with extension (e.g., 'audio.mp3'). Required for base64 data.
• options (object, optional): Same transcription options as other tools

Examples:

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

{
  "data": "data:audio/mp3;base64,//uQx...",
  "filename": "recording.mp3",
  "options": {
    "language_code": "en"
  }
}

submit_transcription

Submit audio for transcription without waiting for completion. Returns immediately with a job ID. Accepts both URLs and local file paths (files will be uploaded automatically).

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:

Using direct API key:

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

Using API key from file:

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

Using EU instance:

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

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

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