ElevenLabs MCP Server

Instructions

Implementation Reference

• src/elevenlabs_mcp/server.py:414-478 (handler)

  Handler function for the 'generate_audio_script' tool within the call_tool method. Parses script input, creates and manages job in database, generates audio via API, and returns embedded audio resource.

  elif name == "generate_audio_script":
      script_json = arguments.get("script", "{}")
      script_parts, parse_debug_info = self.parse_script(script_json)
      debug_info.extend(parse_debug_info)
  
      # Create job record
      job_id = str(uuid.uuid4())
      job = AudioJob(
          id=job_id,
          status="pending",
          script_parts=script_parts,
          total_parts=len(script_parts)
      )
      await self.db.insert_job(job)
      debug_info.append(f"Created job record: {job_id}")
  
      try:
          job.status = "processing"
          await self.db.update_job(job)
  
          output_file, api_debug_info, completed_parts = self.api.generate_full_audio(
              script_parts,
              self.output_dir
          )
          debug_info.extend(api_debug_info)
  
          job.status = "completed"
          job.output_file = str(output_file)
          job.completed_parts = completed_parts
          await self.db.update_job(job)
      except Exception as e:
          job.status = "failed"
          job.error = str(e)
          await self.db.update_job(job)
          raise
      
      # Read the generated audio file and encode it as base64
      with open(output_file, 'rb') as f:
          audio_bytes = f.read()
          audio_base64 = base64.b64encode(audio_bytes).decode('utf-8')
          
      # Generate unique URI for the resource
      filename = Path(output_file).name
      resource_uri = f"audio://{filename}"
          
      # Return both a status message and the audio file content
      return [
          types.TextContent(
              type="text",
              text="\n".join([
                  "Audio generation successful. Debug info:",
                  *debug_info
              ])
          ),
          types.EmbeddedResource(
              type="resource",
              resource=types.BlobResourceContents(
                  uri=resource_uri,
                  name=filename,
                  blob=audio_base64,
                  mimeType="audio/mpeg"
              )
          )
      ]

• src/elevenlabs_mcp/server.py:227-252 (registration)

  Registration of the 'generate_audio_script' tool in list_tools(), including name, description, and input schema definition.

  types.Tool(
      name="generate_audio_script",
      description="""Generate audio from a structured script with multiple voices and actors. 
      Accepts either:
      1. Plain text string
      2. JSON string with format: {
          "script": [
              {
                  "text": "Text to speak",
                  "voice_id": "optional-voice-id",
                  "actor": "optional-actor-name"
              },
              ...
          ]
      }""",
      inputSchema={
          "type": "object",
          "properties": {
              "script": {
                  "type": "string",
                  "description": "JSON string containing script array or plain text. For JSON format, provide an object with a 'script' array containing objects with 'text' (required), 'voice_id' (optional), and 'actor' (optional) fields."
              }
          },
          "required": ["script"]
      }
  ),

• src/elevenlabs_mcp/server.py:63-132 (helper)

  Helper method to parse the script input (JSON or plain text) into structured parts with text, voice_id, and actor.

  def parse_script(self, script_json: str) -> tuple[list[dict], list[str]]:
      """
      Parse the input into a list of script parts and collect debug information.
      Accepts:
      1. A JSON string with a script array containing dialogue parts
      2. Plain text to be converted to speech
      
      Each dialogue part should have:
      - text (required): The text to speak
      - voice_id (optional): The voice to use
      - actor (optional): The actor/character name
      
      Args:
          script_json: Input text or JSON string
          
      Returns:
          tuple containing:
              - list of parsed script parts
              - list of debug information strings
      """
      debug_info = []
      debug_info.append(f"Raw input: {script_json}")
      
      script_array = []
      
      # Remove any leading/trailing whitespace
      script_json = script_json.strip()
      
      try:
          # Try to parse as JSON first
          if script_json.startswith('['):
              # Direct array of script parts
              script_array = json.loads(script_json)
          elif script_json.startswith('{'):
              # Object with script array
              script_data = json.loads(script_json)
              script_array = script_data.get('script', [])
          else:
              # Treat as plain text if not JSON formatted
              script_array = [{"text": script_json}]
      except json.JSONDecodeError as e:
          # If JSON parsing fails and input looks like JSON, raise error
          if script_json.startswith('{') or script_json.startswith('['):
              debug_info.append(f"JSON parsing failed: {str(e)}")
              raise Exception("Invalid JSON format")
          # Otherwise treat as plain text
          debug_info.append("Input is plain text")
          script_array = [{"text": script_json}]
      
      script_parts = []
      for part in script_array:
          if not isinstance(part, dict):
              debug_info.append(f"Skipping non-dict part: {part}")
              continue
              
          text = part.get("text", "").strip()
          if not text:
              debug_info.append("Missing or empty text field")
              raise Exception("Missing required field 'text'")
              
          new_part = {
              "text": text,
              "voice_id": part.get("voice_id"),
              "actor": part.get("actor")
          }
          debug_info.append(f"Created part: {new_part}")
          script_parts.append(new_part)
      
      debug_info.append(f"Final script_parts: {script_parts}")
      return script_parts, debug_info