ElevenLabs MCP Server

Instructions

⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.

Args:
    file_path: Path to the audio file to transcribe
    language_code: ISO 639-3 language code for transcription. If not provided, the language will be detected automatically.
    diarize: Whether to diarize the audio file. If True, which speaker is currently speaking will be annotated in the transcription.
    save_transcript_to_file: Whether to save the transcript to a file.
    return_transcript_to_client_directly: Whether to return the transcript to the client directly.
    output_directory: Directory where files should be saved.
        Defaults to $HOME/Desktop if not provided.

Returns:
    TextContent containing the transcription. If save_transcript_to_file is True, the transcription will be saved to a file in the output directory.

Implementation Reference

• elevenlabs_mcp/server.py:278-323 (handler)

  The core handler function implementing the speech_to_text tool logic: loads audio file, calls ElevenLabs speech-to-text API with options for language, diarization, formats output, and saves or returns the transcript.

  def speech_to_text(
      input_file_path: str,
      language_code: str | None = None,
      diarize: bool = False,
      save_transcript_to_file: bool = True,
      return_transcript_to_client_directly: bool = False,
      output_directory: str | None = None,
  ) -> TextContent:
      if not save_transcript_to_file and not return_transcript_to_client_directly:
          make_error("Must save transcript to file or return it to the client directly.")
      file_path = handle_input_file(input_file_path)
      if save_transcript_to_file:
          output_path = make_output_path(output_directory, base_path)
          output_file_name = make_output_file("stt", file_path.name, output_path, "txt")
      with file_path.open("rb") as f:
          audio_bytes = f.read()
  
      if language_code == "" or language_code is None:
          language_code = None
  
      transcription = client.speech_to_text.convert(
          model_id="scribe_v1",
          file=audio_bytes,
          language_code=language_code,
          enable_logging=True,
          diarize=diarize,
          tag_audio_events=True,
      )
  
      # Format transcript with speaker identification if diarization was enabled
      if diarize:
          formatted_transcript = format_diarized_transcript(transcription)
      else:
          formatted_transcript = transcription.text
  
      if save_transcript_to_file:
          with open(output_path / output_file_name, "w") as f:
              f.write(formatted_transcript)
  
      if return_transcript_to_client_directly:
          return TextContent(type="text", text=formatted_transcript)
      else:
          return TextContent(
              type="text", text=f"Transcription saved to {output_path / output_file_name}"
          )

• elevenlabs_mcp/server.py:260-277 (registration)

  The @mcp.tool decorator that registers the speech_to_text function as an MCP tool, including the schema description for inputs and outputs.

  @mcp.tool(
      description="""Transcribe speech from an audio file and either save the output text file to a given directory or return the text to the client directly.
  
      ⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
  
      Args:
          file_path: Path to the audio file to transcribe
          language_code: ISO 639-3 language code for transcription. If not provided, the language will be detected automatically.
          diarize: Whether to diarize the audio file. If True, which speaker is currently speaking will be annotated in the transcription.
          save_transcript_to_file: Whether to save the transcript to a file.
          return_transcript_to_client_directly: Whether to return the transcript to the client directly.
          output_directory: Directory where files should be saved.
              Defaults to $HOME/Desktop if not provided.
  
      Returns:
          TextContent containing the transcription. If save_transcript_to_file is True, the transcription will be saved to a file in the output directory.
      """
  )

• elevenlabs_mcp/server.py:60-139 (helper)

  Helper function to format diarized transcripts with speaker labels, used conditionally in the speech_to_text handler.

  def format_diarized_transcript(transcription) -> str:
      """Format transcript with speaker labels from diarized response."""
      try:
          # Try to access words array - the exact attribute might vary
          words = None
          if hasattr(transcription, "words"):
              words = transcription.words
          elif hasattr(transcription, "__dict__"):
              # Try to find words in the response dict
              for key, value in transcription.__dict__.items():
                  if key == "words" or (
                      isinstance(value, list)
                      and len(value) > 0
                      and (
                          hasattr(value[0], "speaker_id")
                          if hasattr(value[0], "__dict__")
                          else (
                              "speaker_id" in value[0]
                              if isinstance(value[0], dict)
                              else False
                          )
                      )
                  ):
                      words = value
                      break
  
          if not words:
              return transcription.text
  
          formatted_lines = []
          current_speaker = None
          current_text = []
  
          for word in words:
              # Get speaker_id - might be an attribute or dict key
              word_speaker = None
              if hasattr(word, "speaker_id"):
                  word_speaker = word.speaker_id
              elif isinstance(word, dict) and "speaker_id" in word:
                  word_speaker = word["speaker_id"]
  
              # Get text - might be an attribute or dict key
              word_text = None
              if hasattr(word, "text"):
                  word_text = word.text
              elif isinstance(word, dict) and "text" in word:
                  word_text = word["text"]
  
              if not word_speaker or not word_text:
                  continue
  
              # Skip spacing/punctuation types if they exist
              if hasattr(word, "type") and word.type == "spacing":
                  continue
              elif isinstance(word, dict) and word.get("type") == "spacing":
                  continue
  
              if current_speaker != word_speaker:
                  # Save previous speaker's text
                  if current_speaker and current_text:
                      speaker_label = current_speaker.upper().replace("_", " ")
                      formatted_lines.append(f"{speaker_label}: {' '.join(current_text)}")
  
                  # Start new speaker
                  current_speaker = word_speaker
                  current_text = [word_text.strip()]
              else:
                  current_text.append(word_text.strip())
  
          # Add final speaker's text
          if current_speaker and current_text:
              speaker_label = current_speaker.upper().replace("_", " ")
              formatted_lines.append(f"{speaker_label}: {' '.join(current_text)}")
  
          return "\n\n".join(formatted_lines)
  
      except Exception:
          # Fallback to regular text if something goes wrong
          return transcription.text