ElevenLabs MCP Server

Instructions

Args:
    prompt: Prompt to convert to music. Must provide either prompt or composition_plan.
    output_directory: Directory to save the output audio file
    composition_plan: Composition plan to use for the music. Must provide either prompt or composition_plan.
    music_length_ms: Length of the generated music in milliseconds. Cannot be used if composition_plan is provided.

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

Implementation Reference

• elevenlabs_mcp/server.py:1118-1153 (handler)

  The handler function that implements the core logic of the 'compose_music' tool. It validates inputs, calls the ElevenLabs client to generate music from a prompt or composition plan, saves the audio to a file, and returns the file path.

  def compose_music(
      prompt: str | None = None,
      output_directory: str | None = None,
      composition_plan: MusicPrompt | None = None,
      music_length_ms: int | None = None,
  ) -> TextContent:
      if prompt is None and composition_plan is None:
          make_error(
              f"Either prompt or composition_plan must be provided. Prompt: {prompt}"
          )
  
      if prompt is not None and composition_plan is not None:
          make_error("Only one of prompt or composition_plan must be provided")
  
      if music_length_ms is not None and composition_plan is not None:
          make_error("music_length_ms cannot be used if composition_plan is provided")
  
      output_path = make_output_path(output_directory, base_path)
      output_file_name = make_output_file("music", "", output_path, "mp3")
  
      audio_data = client.music.compose(
          prompt=prompt,
          music_length_ms=music_length_ms,
          composition_plan=composition_plan,
      )
  
      audio_bytes = b"".join(audio_data)
  
      output_path.parent.mkdir(parents=True, exist_ok=True)
      with open(output_path / output_file_name, "wb") as f:
          f.write(audio_bytes)
  
      return TextContent(
          type="text",
          text=f"Success. File saved as: {output_path / output_file_name}.",
      )

• elevenlabs_mcp/server.py:1106-1117 (registration)

  The @mcp.tool decorator registers the 'compose_music' tool with MCP and provides the input schema via the description and type annotations.

  @mcp.tool(
      description="""Convert a prompt to music and save the output audio file to a given directory.
      Directory is optional, if not provided, the output file will be saved to $HOME/Desktop.
  
      Args:
          prompt: Prompt to convert to music. Must provide either prompt or composition_plan.
          output_directory: Directory to save the output audio file
          composition_plan: Composition plan to use for the music. Must provide either prompt or composition_plan.
          music_length_ms: Length of the generated music in milliseconds. Cannot be used if composition_plan is provided.
  
      ⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user."""
  )

• elevenlabs_mcp/server.py:1156-1176 (helper)

  Supporting tool 'create_composition_plan' that generates a MusicPrompt composition plan from a prompt, which can be passed to the compose_music handler.

  @mcp.tool(
      description="""Create a composition plan for music generation. Usage of this endpoint does not cost any credits but is subject to rate limiting depending on your tier. Composition plans can be used when generating music with the compose_music tool.
  
      Args:
          prompt: Prompt to create a composition plan for
          music_length_ms: The length of the composition plan to generate in milliseconds. Must be between 10000ms and 300000ms. Optional - if not provided, the model will choose a length based on the prompt.
          source_composition_plan: An optional composition plan to use as a source for the new composition plan
      """
  )
  def create_composition_plan(
      prompt: str,
      music_length_ms: int | None = None,
      source_composition_plan: MusicPrompt | None = None,
  ) -> MusicPrompt:
      composition_plan = client.music.composition_plan.create(
          prompt=prompt,
          music_length_ms=music_length_ms,
          source_composition_plan=source_composition_plan,
      )
  
      return composition_plan