ElevenLabs MCP Server

Instructions

Implementation Reference

• elevenlabs_mcp/server.py:1177-1207 (handler)

  Core handler function that implements the logic for the 'compose_music' tool. Validates inputs (ensuring exactly one of prompt or composition_plan is provided, and music_length_ms compatibility), generates music using the ElevenLabs client.music.compose API, assembles audio bytes, and handles output via utility functions based on global output_mode.
  def compose_music( prompt: str | None = None, output_directory: str | None = None, composition_plan: MusicPrompt | None = None, music_length_ms: int | None = None, ) -> Union[TextContent, EmbeddedResource]: 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", "", "mp3") audio_data = client.music.compose( prompt=prompt, music_length_ms=music_length_ms, composition_plan=composition_plan, ) audio_bytes = b"".join(audio_data) # Handle different output modes return handle_output_mode(audio_bytes, output_path, output_file_name, output_mode)
• elevenlabs_mcp/server.py:1165-1176 (registration)

  Registers the compose_music tool with the FastMCP server using the @mcp.tool decorator. Provides comprehensive description, argument details, and cost warning.
  @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:1209-1229 (helper)

  Supporting tool 'create_composition_plan' that generates a MusicPrompt object, which can be passed to the compose_music tool's composition_plan parameter. This is a rate-limited but free endpoint.
  @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