Model Context Protocol server for AssemblyAI transcription services
npm install assemblyai-mcp-serverA 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.
- 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
1. Clone or create this project directory
2. Install dependencies:
``bash`
npm install
`
3. Set up your AssemblyAI API key (see Configuration section)
4. Build the TypeScript code:
bash`
npm run build
You need an AssemblyAI API key to use this server. Get one from AssemblyAI.
Set the environment variable:
`bash`
export ASSEMBLYAI_API_KEY="your-api-key-here"
Or create a .env file:``
ASSEMBLYAI_API_KEY=your-api-key-here
Start the MCP server:
`bash`
npm start
For development with auto-rebuild:
`bash`
npm run watch
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 fileoptions
- (object, optional): Transcription optionsspeaker_labels
- (boolean): Enable speaker diarizationlanguage_code
- (string): Specify language (e.g., "en")punctuate
- (boolean): Add punctuationformat_text
- (boolean): Format text for readability
Example:
`json`
{
"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 fileoptions
- (object, optional): Same as transcribe_url
Example:
`json`
{
"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 pathoptions
- (object, optional): Same transcription options
Example:
`json`
{
"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:
`json`
{
"transcriptId": "1234567890"
}
#### transcript://{id}
Access transcript data directly by ID. Provides structured JSON with all transcript information.
Example URI: transcript://1234567890
Returns:
`json`
{
"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"
}
Add to your claude_desktop_config.json:
`json`
{
"mcpServers": {
"assemblyai": {
"command": "node",
"args": ["/path/to/assemblyai-mcp-server/dist/index.js"],
"env": {
"ASSEMBLYAI_API_KEY": "your-api-key-here"
}
}
}
}
The server uses stdio transport, so it's compatible with any MCP client that supports this transport method.
or transcribe_file for immediate results
2. The tool waits for completion and returns the full transcript$3
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$3
`json
{
"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 transcriptsDevelopment
$3
`bash
npm run build
`$3
`bash
npm run dev
`$3
`bash
npm run watch
``- Node.js 18.0.0 or higher
- AssemblyAI API key
- MCP-compatible client
MIT License
For AssemblyAI API issues, visit AssemblyAI Documentation.
For MCP protocol questions, see Model Context Protocol.