### Setup virtual environment

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/README.md

Create a virtual environment and install development dependencies using uv.

```bash
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
```

--------------------------------

### File Path Resolution Examples

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/configuration.md

Examples of absolute, relative, and home-directory-expanded paths used by the server.

```bash
# Absolute path (always works)
/home/user/audio/input.wav

# Relative to ELEVENLABS_MCP_BASE_PATH
recordings/session1.wav  # Resolves to ~/Music/recordings/session1.wav
                         # (if ELEVENLABS_MCP_BASE_PATH=~/Music)

# Home directory expansion
~/Desktop/file.mp3       # Expands to /home/user/Desktop/file.mp3

# Platform-specific paths
/Users/user/Desktop/...  # macOS
C:/Users/user/Desktop/.. # Windows (with wsl or native)
```

--------------------------------

### Execute play_audio usage examples

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/models-and-info.md

Examples demonstrating how to trigger audio playback for both generated TTS files and existing recordings.

```python
# Play a generated TTS file
result = play_audio(input_file_path="/path/to/generated_speech.mp3")
# Returns: "Successfully played audio file: /path/to/generated_speech.mp3"

# Play a transcribed audio file
result = play_audio(input_file_path="/home/user/Downloads/recording.wav")
```

--------------------------------

### Resource Access Examples

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/models-and-info.md

Example URIs for accessing audio and text files when output mode is set to resources or both.

```text
elevenlabs://tts_hello_20250403_154930.mp3
elevenlabs://stt_transcript_20250403_154930.txt
```

--------------------------------

### Examples of get_output_mode_description

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Shows the return values for different output mode configurations.

```python
get_output_mode_description("files")
# Returns: "Saves output file to directory (default: $HOME/Desktop)"

get_output_mode_description("resources")
# Returns: "Returns output as base64-encoded MCP resource"
```

--------------------------------

### Execute try_find_similar_files example

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Demonstrates retrieving a limited number of matching audio/video files.

```python
try_find_similar_files("audio.wav", Path("/home/user/audio"), take_n=3)
# Returns: [Path("/home/user/audio/audio01.wav"), Path("/home/user/audio/audio_v2.wav")]
```

--------------------------------

### Run tests

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/README.md

Execute the test suite to verify the installation.

```bash
./scripts/test.sh
# Or with options
./scripts/test.sh --verbose --fail-fast
```

--------------------------------

### Install and Configure ElevenLabs MCP

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/README.md

Commands to install the package and generate the configuration string for MCP clients.

```bash
pip install elevenlabs-mcp
```

```bash
python -m elevenlabs_mcp --api-key={{PUT_YOUR_API_KEY_HERE}} --print
```

--------------------------------

### Execute find_similar_filenames example

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Demonstrates finding files similar to 'audio.wav' with a specified directory path.

```python
find_similar_filenames("audio.wav", Path("/home/user/audio"))
# Returns: [
#   ("/home/user/audio/audio01.wav", 89),
#   ("/home/user/audio/audio_backup.wav", 78)
# ]
```

--------------------------------

### Example ConvaiAgent Instance

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/types.md

JSON representation of a fully configured conversational agent.

```json
{
    "name": "Customer Support Bot",
    "agent_id": "agent_abc123def456",
    "system_prompt": "You are a helpful customer support representative...",
    "voice_id": "cgSgspJ2msm6clMCkdW9",
    "language": "en",
    "llm": "gemini-2.0-flash-001"
}
```

--------------------------------

### Handle input file usage examples

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Demonstrates successful path resolution and error handling with fuzzy matching suggestions.

```python
# Valid file
handle_input_file("/path/to/audio.wav")
# Returns: Path("/path/to/audio.wav")

# File not found with suggestions
handle_input_file("/path/to/audio.wav")  # If audio01.wav exists nearby
# Raises: ElevenLabsMcpError("File (...audio.wav) does not exist. Did you mean any of these files: /path/to/audio01.wav?")
```

--------------------------------

### Create a Customer Service Agent

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/conversational-ai.md

Example of initializing a support-focused agent with specific voice and timeout settings.

```python
result = create_agent(
    name="Customer Support Bot",
    first_message="Hello! Thank you for contacting our support team. How can I assist you today?",
    system_prompt="You are a helpful customer support representative. You answer questions about products, process returns, and provide technical support. You are empathetic and patient.",
    voice_id="EXAkvLmy5sUP4z7XtoVJ",  # Sarah's voice
    language="en",
    llm="gemini-2.0-flash-001",
    temperature=0.4,  # More deterministic for consistency
    asr_quality="high",
    model_id="eleven_turbo_v2",
    turn_timeout=10,
    max_duration_seconds=600
)
# Returns: Agent ID like "agent_abc123def456"
```

--------------------------------

### Local Development Environment Variables

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/configuration.md

Example .env file configuration for local development and testing.

```env
ELEVENLABS_API_KEY=sk-abc123xyz789
ELEVENLABS_MCP_BASE_PATH=./audio_files
ELEVENLABS_MCP_OUTPUT_MODE=files
ELEVENLABS_API_RESIDENCY=us
ELEVENLABS_DEFAULT_VOICE_ID=cgSgspJ2msm6clMCkdW9
```

--------------------------------

### Check file writeability examples

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Demonstrates checking write permissions for specific paths.

```python
is_file_writeable(Path("/tmp/output.mp3"))     # True (if /tmp is writeable)
is_file_writeable(Path("/root/protected"))     # False (if /root not accessible)
```

--------------------------------

### Example usage of handle_output_mode

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Demonstrates calling the function with the 'resources' mode to return an EmbeddedResource.

```python
response = handle_output_mode(
    audio_bytes,
    Path("/home/user/audio"),
    "output.mp3",
    "resources"
)
# Returns: EmbeddedResource with base64 audio
```

--------------------------------

### Execute handle_large_text example

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Demonstrates offloading long transcript content to a temporary file.

```python
result = handle_large_text(very_long_transcript, max_length=50000)
# If transcript > 50000 chars:
# Returns: "Content saved to temporary file: /tmp/tmpXXXXXX.txt\nUse the Read tool to access the full content."
```

--------------------------------

### Check audio file extension examples

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Demonstrates usage of check_audio_file with various file types.

```python
check_audio_file(Path("audio.wav"))      # True
check_audio_file(Path("video.mp4"))      # True
check_audio_file(Path("image.jpg"))      # False
check_audio_file(Path("document.pdf"))   # False
```

--------------------------------

### Create a Conversational AI Tutoring Agent

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/conversational-ai.md

Example of initializing an educational agent with custom LLM settings and privacy configurations.

```python
result = create_agent(
    name="Math Tutor",
    first_message="Hi! I'm your math tutor. What topic would you like to learn about today?",
    system_prompt="You are an engaging and patient math tutor. Explain concepts clearly, provide examples, and encourage the student. Adapt your explanations to the student's level.",
    language="en",
    llm="gpt-4-turbo",
    temperature=0.6,
    max_tokens=1000,
    asr_quality="high",
    optimize_streaming_latency=2,
    max_duration_seconds=1800,  # 30 minutes
    record_voice=False  # Don't record tutoring sessions for privacy
)
```

--------------------------------

### Generate music with custom output directory

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/music-generation.md

Example of specifying a custom output directory and selecting a specific model version.

```python
result = video_to_music(
    input_file_paths=["/videos/project.mp4"],
    tags=["atmospheric", "minimal"],
    output_directory="/music/generated",
    model_id="music_v2"
)
```

--------------------------------

### Example McpLanguage Instance

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/types.md

JSON representation of a language object.

```json
{
    "language_id": "en",
    "name": "English"
}
```

--------------------------------

### Invoke list_models

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/models-and-info.md

Basic usage example for calling the list_models function.

```python
models = list_models()
# Returns all available TTS models with their language support
```

--------------------------------

### Generate a resource URI

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Example of generating a URI string in the elevenlabs:// format.

```python
generate_resource_uri("audio.mp3")
# Returns: "elevenlabs://audio.mp3"
```

--------------------------------

### Use get_mime_type for file extensions

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Examples of mapping various file extensions to their corresponding MIME types.

```python
get_mime_type("mp3")          # "audio/mpeg"
get_mime_type(".wav")         # "audio/wav"
get_mime_type("txt")          # "text/plain"
get_mime_type("unknown")      # "application/octet-stream"
```

--------------------------------

### Generic API Error Examples

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/errors.md

Examples of common HTTP status error messages returned by the ElevenLabs API.

```text
Request failed with status 401: Invalid API key
Request failed with status 429: Rate limit exceeded
Request failed with status 503: Service unavailable
```

--------------------------------

### Example McpModel JSON

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/types.md

JSON representation of an McpModel object.

```json
{
    "id": "eleven_multilingual_v2",
    "name": "Eleven Multilingual v2",
    "languages": [
        {"language_id": "en", "name": "English"},
        {"language_id": "fr", "name": "French"},
        {"language_id": "de", "name": "German"}
    ]
}
```

--------------------------------

### Execute parse_conversation_transcript example

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Demonstrates converting a list of transcript entries into a formatted string.

```python
entries = [
    {"role": "user", "message": "Hello", "timestamp": "00:00:01"},
    {"role": "agent", "message": "Hi there!", "timestamp": "00:00:02"}
]
text, is_temp = parse_conversation_transcript(entries)
# Returns: ("user: Hello\nagent: Hi there!", False)
```

--------------------------------

### Search Voice Library Usage Examples

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/voice-management.md

Demonstrates how to perform searches, retrieve specific pages, and paginate through voice library results.

```python
# Search for female voices
result = search_voice_library(search="female", page=0, page_size=20)

# Get first page of all available voices
result = search_voice_library(page=0, page_size=50)

# Paginate through results
page1 = search_voice_library(page=0, page_size=10)
page2 = search_voice_library(page=1, page_size=10)
```

--------------------------------

### Transform speech using speech_to_speech

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/audio-processing.md

Examples demonstrating voice transformation with default settings, custom voice selection, and specific output directories.

```python
# Transform speech to "Sarah" voice
result = speech_to_speech(
    input_file_path="/path/to/original_speech.wav",
    voice_name="Sarah"
)

# Transform to Adam (default)
result = speech_to_speech(
    input_file_path="/path/to/recording.mp3"
)

# With custom output directory
result = speech_to_speech(
    input_file_path="/path/to/speech.wav",
    voice_name="Luna",
    output_directory="/audio/transformed"
)
```

--------------------------------

### Model return structure

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/models-and-info.md

Example of the JSON structure returned by the list_models tool.

```json
[
    {
        "id": "eleven_multilingual_v2",
        "name": "Eleven Multilingual v2",
        "languages": [
            {
                "language_id": "en",
                "name": "English"
            },
            {
                "language_id": "fr",
                "name": "French"
            },
            # ... more languages
        ]
    },
    # ... more models
]
```

--------------------------------

### Isolate audio usage example

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/audio-processing.md

Demonstrates how to call the isolate_audio function with a specific input file and output directory.

```python
result = isolate_audio(
    input_file_path="/path/to/noisy_recording.wav",
    output_directory="/path/to/output"
)
# Returns isolated audio file (background noise removed)
```

--------------------------------

### Add knowledge base to agent

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/conversational-ai.md

Examples of adding knowledge bases via file path, URL, or raw text. Exactly one of these parameters must be provided.

```python
result = add_knowledge_base_to_agent(
    agent_id="agent_abc123def456",
    knowledge_base_name="Product Manual",
    input_file_path="/path/to/product_manual.pdf"
)
```

```python
result = add_knowledge_base_to_agent(
    agent_id="agent_abc123def456",
    knowledge_base_name="Company FAQ",
    url="https://example.com/faq"
)
```

```python
result = add_knowledge_base_to_agent(
    agent_id="agent_abc123def456",
    knowledge_base_name="Policies",
    text="Refund Policy: Items can be returned within 30 days of purchase for a full refund..."
)
```

--------------------------------

### Generate music for a single video

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/music-generation.md

Example of generating music for one video file using a descriptive prompt and style tags.

```python
result = video_to_music(
    input_file_paths=["/path/to/promotional_video.mp4"],
    description="Build suspense with dramatic strings, then resolve with uplifting triumphant ending",
    tags=["cinematic", "dramatic", "inspiring"]
)
```

--------------------------------

### Generate music for multiple video files

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/music-generation.md

Example of concatenating multiple video files to generate a single continuous music track.

```python
result = video_to_music(
    input_file_paths=[
        "/path/to/scene1.mp4",
        "/path/to/scene2.mp4",
        "/path/to/scene3.mp4"
    ],
    description="Uplifting and energetic throughout, with variations matching scene changes",
    tags=["uplifting", "energetic", "modern"]
)
# Videos are automatically concatenated, music generated for combined duration
```

--------------------------------

### Generate sound effects with text_to_sound_effects

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/audio-processing.md

Examples of generating various sound effects with different duration, looping, and output format configurations.

```python
# Generate a 2-second thunderstorm sound
result = text_to_sound_effects(
    text="Heavy thunder with rain and wind",
    duration_seconds=2.0
)

# Generate a looping doorbell sound
result = text_to_sound_effects(
    text="Electronic doorbell ringing",
    duration_seconds=1.0,
    loop=True
)

# Generate a long ambient sound
result = text_to_sound_effects(
    text="Busy office environment with typing and phone calls",
    duration_seconds=5.0,
    output_format="mp3_44100_192"
)
```

--------------------------------

### Make an outbound call

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/phone-calls.md

Basic usage example for initiating a call with specific agent and phone number identifiers.

```python
result = make_outbound_call(
    agent_id="agent_abc123def456",
    agent_phone_number_id="phone_xyz789abc123",
    to_number="+12025551234"
)
# Returns: "Outbound call initiated via Twilio: ..."
```

--------------------------------

### Search Voices Usage Examples

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/voice-management.md

Demonstrates various ways to invoke the search_voices function with different search and sorting criteria.

```python
# Search for all voices, sorted by name descending
voices = search_voices()

# Search for specific voice by name
voices = search_voices(search="Adam")

# Search and sort by creation date
voices = search_voices(search="premium", sort="created_at_unix", sort_direction="desc")
```

--------------------------------

### List Phone Numbers Python Example

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/phone-calls.md

Retrieves a formatted list of all phone numbers associated with the account, including provider details and agent assignments.

```python
result = list_phone_numbers()
# Returns formatted text like:
# "Phone Numbers:
#
# Phone Number: +12025551111
# ID: phone_abc123
# Provider: Twilio
# Label: Main Customer Line
# Assigned Agent: Customer Support Bot (ID: agent_abc123def456)
#
# Phone Number: +12025552222
# ID: phone_def456
# Provider: SIP trunk
# Label: Sales Line
# Assigned Agent: None"
```

--------------------------------

### Clone the repository

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/README.md

Initial steps to download the project source code.

```bash
git clone https://github.com/elevenlabs/elevenlabs-mcp
cd elevenlabs-mcp
```

--------------------------------

### Example McpVoice JSON

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/types.md

JSON representation of an McpVoice object.

```json
{
    "id": "cgSgspJ2msm6clMCkdW9",
    "name": "Adam",
    "category": "professional",
    "fine_tuning_status": None
}
```

--------------------------------

### Create Voice from Preview Usage

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/voice-management.md

Demonstrates the workflow of generating a voice preview and subsequently saving it to the voice library.

```python
# First, use text_to_voice to generate previews
previews = text_to_voice(
    voice_description="A warm, friendly female voice with a slight accent"
)
# This returns generated_voice_id in the output

# Then, create the voice from the preview
result = create_voice_from_preview(
    generated_voice_id="Ya2J5uIa5Pq14DNPsbC1",
    voice_name="Warm Female Assistant",
    voice_description="Friendly, warm female voice for customer service applications"
)
# Returns: TextContent with success message and voice ID
```

--------------------------------

### Configure Development and Testing

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/configuration.md

Use this configuration to enable both immediate resource access and persistent file storage.

```json
{
  "env": {
    "ELEVENLABS_API_KEY": "sk-abc123xyz789",
    "ELEVENLABS_MCP_OUTPUT_MODE": "both",
    "ELEVENLABS_MCP_BASE_PATH": "./temp"
  }
}
```

--------------------------------

### Configure environment variables

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/README.md

Prepare the .env file for API key configuration.

```bash
cp .env.example .env
# Edit .env and add your API key
```

--------------------------------

### Iterate on Existing Composition Plans

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/music-generation.md

Demonstrates how to use an existing plan as a base to refine a new composition.

```python
# Create initial plan
base_plan = create_composition_plan(
    prompt="Upbeat electronic dance track"
)

# Refine the plan
refined_plan = create_composition_plan(
    prompt="Same track but with more bass and slower tempo",
    source_composition_plan=base_plan,
    model_id="music_v2"
)

# Generate from refined plan
music = compose_music(composition_plan=refined_plan)
```

--------------------------------

### Create a Multi-Section Composition Plan

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/music-generation.md

Generates a plan for a specific duration and model, then uses it to trigger music generation.

```python
plan = create_composition_plan(
    prompt="A cinematic score with multiple movements",
    music_length_ms=120000,  # 2 minutes
    model_id="music_v2"
)
# Returns dict with chunks describing different sections

# Now use the plan to generate music
music = compose_music(
    composition_plan=plan,
    model_id="music_v2"
)
```

--------------------------------

### Diarization Output Format

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/speech-to-text.md

Example of the transcript format when diarization is enabled, showing speaker identification labels.

```text
SPEAKER_1: First sentence from speaker one.

SPEAKER_2: A response from speaker two.

SPEAKER_1: Another turn from speaker one.
```

--------------------------------

### Get agent details

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/conversational-ai.md

Retrieves detailed configuration and metadata for a specific agent using its unique identifier.

```python
result = get_agent(agent_id="agent_abc123def456")
# Returns detailed information about the agent
```

--------------------------------

### Upload Music for Inpainting

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/music-inpainting.md

Uploads a local audio file to the server. Requires an enterprise account with inpainting permissions.

```python
result = upload_music_for_inpainting(
    input_file_path="/path/to/my_music.mp3",
    extract_composition_plan="music_v2"
)
# Returns:
# song_id: song_abc123def456
# Extracted composition plan (music_v2):
# {
#   "chunks": [...]
# }
```

```python
result = upload_music_for_inpainting(
    input_file_path="/path/to/track.wav",
    extract_composition_plan=None
)
# Returns: song_id only
```

--------------------------------

### Missing Evaluation Criteria Fields Example

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/errors.md

Demonstrates an incomplete evaluation criterion object missing required fields.

```python
# Missing 'name' field
extra_evaluation_criteria = [
    {
        "id": "test",
        # Missing "name" and "conversation_goal_prompt"
    }
]
```

--------------------------------

### Configure Serverless and Enterprise Environments

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/configuration.md

Advanced configurations for serverless deployment and enterprise data residency requirements.

```json
{
  "mcpServers": {
    "ElevenLabs": {
      "command": "python",
      "args": ["-m", "elevenlabs_mcp"],
      "env": {
        "ELEVENLABS_API_KEY": "sk-abc123xyz789",
        "ELEVENLABS_MCP_OUTPUT_MODE": "resources"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "ElevenLabs": {
      "command": "uvx",
      "args": ["elevenlabs-mcp"],
      "env": {
        "ELEVENLABS_API_KEY": "sk-abc123xyz789",
        "ELEVENLABS_API_RESIDENCY": "eu",
        "ELEVENLABS_MCP_BASE_PATH": "/data/audio",
        "ELEVENLABS_MCP_OUTPUT_MODE": "both"
      }
    }
  }
}
```

--------------------------------

### Create voice previews with custom output directory

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/voice-design.md

Saves the generated preview files to a specific file system path.

```python
previews = text_to_voice(
    voice_description="A professional narrator voice",
    output_directory="/path/to/voice_previews"
)
# Preview files saved to specified directory
```

--------------------------------

### Configure both output mode

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/configuration.md

Enables saving files to disk while simultaneously returning them as MCP resources. Provides maximum flexibility but has the highest resource overhead.

```json
{
  "env": {
    "ELEVENLABS_API_KEY": "your-api-key",
    "ELEVENLABS_MCP_OUTPUT_MODE": "both",
    "ELEVENLABS_MCP_BASE_PATH": "~/Music/generated"
  }
}
```

--------------------------------

### Create a custom voice

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/00-START-HERE.md

Generates a voice preview from a description and saves it as a new voice.

```python
# Step 1: Design voice
previews = text_to_voice(
    voice_description="Warm female voice"
)

# Step 2: Create from preview
create_voice_from_preview(
    generated_voice_id="Ya2J5uIa5Pq14DNPsbC1",
    voice_name="My Voice"
)
```

--------------------------------

### Get output mode description in Python

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Defines the function signature for retrieving a human-readable description of the current output mode.

```python
def get_output_mode_description(output_mode: str) -> str
```

--------------------------------

### Workflow for designing, previewing, and creating a voice

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/voice-design.md

A complete sequence demonstrating generating voice previews, selecting a favorite, creating a permanent voice, and using it for text-to-speech.

```python
# Step 1: Generate three preview variations
previews = text_to_voice(
    voice_description="A warm, friendly female voice with a slight Italian accent",
    text="Hello, welcome to our service. How can I help you today?"
)
# Output message contains three generated_voice_ids, e.g.:
# "Generated voice IDs are: Ya2J5uIa5Pq14DNPsbC1, Za3J5vIb6Rr25DNQtdD2, Bb4K6wJc7Ss36EOQueFm"

# Step 2: Listen to previews and choose favorite
# (User would listen to preview files and decide which voice to use)

# Step 3: Create the voice permanently from favorite preview
result = create_voice_from_preview(
    generated_voice_id="Ya2J5uIa5Pq14DNPsbC1",
    voice_name="Warm Italian Assistant",
    voice_description="A warm, friendly female voice with a slight Italian accent. Ideal for customer service and assistant applications."
)
# Returns: TextContent with "Success. Voice created: Warm Italian Assistant with ID: voice_abc123def456"

# Step 4: Use the created voice in text_to_speech
audio = text_to_speech(
    text="Thank you for calling, how can I assist?",
    voice_id="voice_abc123def456"
)
```

--------------------------------

### Customer Recall System Implementation

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/phone-calls.md

Demonstrates listing available resources, initiating an outbound call, and retrieving conversation details.

```python
# List available agents and phones
agents = list_agents()
phones = list_phone_numbers()

# Get agent and phone IDs from responses
agent_id = "agent_customer_support"
phone_id = "phone_main_line"

# Call customer
result = make_outbound_call(
    agent_id=agent_id,
    agent_phone_number_id=phone_id,
    to_number="+14165551234"
)

# Later, retrieve conversation
conversations = list_conversations(agent_id=agent_id)
# Extract conversation_id from response
conversation = get_conversation(conversation_id="conv_xyz789")
```

--------------------------------

### Configure resources output mode

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/configuration.md

Configures the server to return audio as base64-encoded MCP resources without writing to disk. Suitable for serverless or containerized environments.

```json
{
  "env": {
    "ELEVENLABS_API_KEY": "your-api-key",
    "ELEVENLABS_MCP_OUTPUT_MODE": "resources"
  }
}
```

--------------------------------

### Create basic voice previews

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/voice-design.md

Generates three voice variations based on a provided description.

```python
previews = text_to_voice(
    voice_description="A warm, friendly female voice with a British accent"
)
# Returns three preview audio files with different voice variations
```

--------------------------------

### Configure files output mode

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/configuration.md

Sets the server to save generated files to the local disk. Requires write access to the specified base path.

```json
{
  "env": {
    "ELEVENLABS_API_KEY": "your-api-key",
    "ELEVENLABS_MCP_OUTPUT_MODE": "files",
    "ELEVENLABS_MCP_BASE_PATH": "~/Desktop"
  }
}
```

--------------------------------

### create_composition_plan

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/music-generation.md

Creates a structured composition plan for advanced music generation control based on a prompt and optional parameters.

```APIDOC
## create_composition_plan

### Description
Creates a structured composition plan for advanced music generation control. This function is a read-only operation and does not cost credits.

### Signature
`create_composition_plan(prompt: str, music_length_ms: int | None = None, source_composition_plan: dict | None = None, model_id: Literal["music_v1", "music_v2"] = "music_v2") -> dict`

### Parameters
- **prompt** (str) - Required - Prompt describing the desired composition.
- **music_length_ms** (int) - Optional - Target length in milliseconds (10000-300000). If not provided, model chooses length.
- **source_composition_plan** (dict) - Optional - An existing composition plan to use as a starting point. Must match the shape of model_id.
- **model_id** (str) - Optional - Model to plan for: "music_v1" or "music_v2". Defaults to "music_v2".

### Return Type
`dict` - Returns a composition plan structure specific to the chosen model_id.

### Usage Example
```python
plan = create_composition_plan(
    prompt="A cinematic score with multiple movements",
    music_length_ms=120000,
    model_id="music_v2"
)
```
```

--------------------------------

### voice_clone(name: str, files: list[str], description: str | None)

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/voice-management.md

Creates an instant voice clone from a list of provided audio files.

```APIDOC
## voice_clone(name: str, files: list[str], description: str | None)

### Description
Creates an instant voice clone from provided audio files. The created voice is instantly available for use.

### Parameters
- **name** (str) - Required - Name for the cloned voice. Must be unique.
- **files** (list[str]) - Required - Paths to audio files for voice cloning.
- **description** (str) - Optional - Optional description or metadata for the cloned voice.

### Supported Audio Formats
.wav, .mp3, .m4a, .aac, .ogg, .flac, .mp4, .avi, .mov, .wmv

### Usage Example
```python
result = voice_clone(
    name="John Custom Voice",
    files=["/path/to/sample1.wav", "/path/to/sample2.wav"],
    description="Custom voice trained on John's voice samples"
)
```
```

--------------------------------

### View Documentation Directory Structure

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/00-START-HERE.md

A visual representation of the project's documentation file hierarchy.

```text
├── 00-START-HERE.md              ← You are here
├── README.md                     ← Project overview
├── INDEX.md                      ← Navigation guide (use this!)
├── DOCUMENTATION_SUMMARY.md      ← What's documented
│
├── Configuration & Reference
│   ├── configuration.md          ← Environment variables
│   ├── types.md                  ← Data models
│   └── errors.md                 ← Error handling
│
└── api-reference/
    ├── text-to-speech.md
    ├── speech-to-text.md
    ├── audio-processing.md
    ├── voice-management.md
    ├── voice-design.md
    ├── music-generation.md
    ├── music-inpainting.md
    ├── conversational-ai.md
    ├── phone-calls.md
    ├── models-and-info.md
    └── utilities.md
```

--------------------------------

### Implement Output Type Unions

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/types.md

Demonstrates tools returning different content types based on the configured output mode.

```python
def text_to_speech(...) -> Union[TextContent, EmbeddedResource]:
    # Returns TextContent in 'files' mode
    # Returns EmbeddedResource in 'resources' or 'both' modes
```

--------------------------------

### Configure environment variables

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/00-START-HERE.md

Required environment settings for API authentication and file output management.

```json
{
  "env": {
    "ELEVENLABS_API_KEY": "your-api-key-here",
    "ELEVENLABS_MCP_OUTPUT_MODE": "files",
    "ELEVENLABS_MCP_BASE_PATH": "~/Desktop"
  }
}
```

--------------------------------

### Create an AI agent

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/00-START-HERE.md

Initializes a new conversational AI agent with a name, greeting, and system instructions.

```python
create_agent(
    name="Customer Support",
    first_message="Hi, how can I help?",
    system_prompt="You are a helpful support agent..."
)
```

--------------------------------

### Workflow: Find phone number and agent before calling

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/phone-calls.md

A multi-step workflow demonstrating how to retrieve available resources before executing the call.

```python
# Step 1: List available phone numbers
phones = list_phone_numbers()
# Output shows available phone IDs and numbers

# Step 2: List available agents
agents = list_agents()
# Output shows available agent IDs

# Step 3: Make the call
result = make_outbound_call(
    agent_id="agent_abc123def456",
    agent_phone_number_id="phone_xyz789abc123",
    to_number="+14165551234"
)
```

--------------------------------

### Create voice previews with custom text

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/voice-design.md

Uses specific text for the voice preview instead of the system-generated default.

```python
previews = text_to_voice(
    voice_description="A youthful male voice with enthusiasm and energy",
    text="This is a sample sentence to demonstrate the voice quality."
)
# All three preview voices will use the same sample text
```

--------------------------------

### Generate music with a simple prompt

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/music-generation.md

Basic usage of compose_music to generate a 30-second track from a text prompt.

```python
result = compose_music(
    prompt="Upbeat electronic dance music with progressive build-up, 130 BPM",
    music_length_ms=30000  # 30 seconds
)
```

--------------------------------

### Configure Claude Desktop for ElevenLabs MCP

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/README.md

Add this configuration to your claude_desktop_config.json file to register the ElevenLabs MCP server using the uvx package runner.

```json
{
  "mcpServers": {
    "ElevenLabs": {
      "command": "uvx",
      "args": ["elevenlabs-mcp"],
      "env": {
        "ELEVENLABS_API_KEY": "<insert-your-api-key-here>"
      }
    }
  }
}
```

--------------------------------

### Generate music from prompt

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/00-START-HERE.md

Creates music based on a text prompt for a specified duration in milliseconds.

```python
compose_music(
    prompt="Upbeat electronic dance music",
    music_length_ms=60000
)
```

--------------------------------

### Composition Plan Structure for music_v1

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/music-generation.md

The expected dictionary structure for a music_v1 composition plan.

```python
{
    "positive_global_styles": ["epic", "orchestral"],
    "negative_global_styles": ["vocals"],
    "sections": [
        {
            "description": "Intro",
            "duration_ms": 10000
        },
        # Additional sections...
    ]
}
```

--------------------------------

### Configure Low-Latency Mode

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/configuration.md

Use this configuration to avoid disk I/O by setting the output mode to resources.

```json
{
  "env": {
    "ELEVENLABS_API_KEY": "sk-abc123xyz789",
    "ELEVENLABS_MCP_OUTPUT_MODE": "resources"
  }
}
```

--------------------------------

### Reference Documentation Sections

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/INDEX.md

Use these patterns to link to specific files or line ranges within the documentation.

```text
api-reference/text-to-speech.md:L50-L100  # Specific lines
api-reference/conversational-ai.md         # Entire file
```

--------------------------------

### Handle File Does Not Exist Error

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/errors.md

Triggered when the provided input file path is invalid or inaccessible.

```python
# Raises: ElevenLabsMcpError("File (/path/to/file.wav) does not exist")
speech_to_text(input_file_path="/nonexistent/file.wav")
```

--------------------------------

### Function Signature for create_composition_plan

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/music-generation.md

Defines the parameters and return type for the composition planning function.

```python
def create_composition_plan(
    prompt: str,
    music_length_ms: int | None = None,
    source_composition_plan: dict | None = None,
    model_id: Literal["music_v1", "music_v2"] = "music_v2",
) -> dict
```

--------------------------------

### text_to_speech(text, voice_id=None, voice_name=None, stability=None, similarity_boost=None, speed=None, model_id=None, output_format=None, output_directory=None, language=None)

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/text-to-speech.md

Converts input text into an audio file using the specified voice and settings.

```APIDOC
## text_to_speech

### Description
Converts the provided text into speech using an ElevenLabs voice. The function supports selecting voices by name or ID and allows for fine-tuning of audio parameters.

### Parameters
- **text** (str) - Required - The text content to convert to speech.
- **voice_id** (str) - Optional - The unique identifier of the voice to use.
- **voice_name** (str) - Optional - The name of the voice to use.
- **stability** (float) - Optional - Stability setting for the voice.
- **similarity_boost** (float) - Optional - Similarity boost setting for the voice.
- **speed** (float) - Optional - Playback speed multiplier.
- **model_id** (str) - Optional - The ID of the ElevenLabs model to use.
- **output_format** (str) - Optional - The desired audio output format (e.g., mp3_44100_192).
- **output_directory** (str) - Optional - Custom directory path to save the generated audio file.
- **language** (str) - Optional - Language code for multilingual models.

### Return Type
Union[TextContent, EmbeddedResource]
- **files mode**: Returns `TextContent` with a success message and file path.
- **resources mode**: Returns `EmbeddedResource` with base64-encoded audio data.
- **both mode**: Returns `EmbeddedResource` with the file saved to disk.

### Errors
- **ElevenLabsMcpError**: Raised if text is empty, both voice_id and voice_name are provided, or the voice name is not found.
- **API error**: Raised for invalid API keys or ElevenLabs service failures.
```

--------------------------------

### create_voice_from_preview

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/voice-design.md

Adds a previously generated voice preview to your permanent voice library. This operation requires a valid generated_voice_id from a recent text_to_voice call.

```APIDOC
## create_voice_from_preview

### Description
Adds a previously generated voice preview to your permanent voice library. This operation makes an API call to ElevenLabs which may incur costs.

### Signature
`create_voice_from_preview(generated_voice_id: str, voice_name: str, voice_description: str) -> TextContent`

### Parameters
- **generated_voice_id** (str) - Required - The ID of a voice generated by text_to_voice.
- **voice_name** (str) - Required - Unique name for the voice in your library.
- **voice_description** (str) - Required - A detailed description of the voice characteristics.

### Return Type
`TextContent` containing confirmation, voice name, and the new permanent voice ID.

### Usage Example
```python
result = create_voice_from_preview(
    generated_voice_id="Ya2J5uIa5Pq14DNPsbC1",
    voice_name="Warm Italian Assistant",
    voice_description="A warm, friendly female voice with a slight Italian accent."
)
```
```

--------------------------------

### upload_music_for_inpainting

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/music-inpainting.md

Uploads a local audio file to the server to generate a song_id, which can then be used in composition plans for inpainting. Optionally extracts a composition plan from the audio.

```APIDOC
## upload_music_for_inpainting

### Description
Uploads an existing audio file to enable inpainting workflows. Returns a song_id for use in composition plans.

### Parameters
- **input_file_path** (str) - Required - Path to a local audio file to upload. Must be absolute or relative to ELEVENLABS_MCP_BASE_PATH.
- **extract_composition_plan** (str) - Optional - Extract composition plan using this model: 'music_v1', 'music_v2', or None (skip extraction). Defaults to 'music_v2'.

### Requirements
- Gated to enterprise customers with inpainting access.
- Requires valid ElevenLabs API key with inpainting permissions.

### Supported Audio Formats
.wav, .mp3, .m4a, .aac, .ogg, .flac

### Return Type
TextContent containing song_id and optional composition_plan.

### Usage Example
```python
result = upload_music_for_inpainting(
    input_file_path="/path/to/my_music.mp3",
    extract_composition_plan="music_v2"
)
```
```

--------------------------------

### Composition Plan Structure for music_v2

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/music-generation.md

The expected dictionary structure for a music_v2 composition plan.

```python
{
    "chunks": [
        {
            "text": "Opening section description",
            "duration_ms": 10000,
            "positive_styles": ["cinematic", "orchestral"],
            "negative_styles": ["vocals"],
            "context_adherence": 0.7,
            # Optional conditioning for inpainting:
            # "conditioning_ref": "song_id",
            # "condition_strength": 0.5
        },
        # Additional chunks...
    ]
}
```

--------------------------------

### Define create_voice_from_preview function signature

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/voice-design.md

The function signature for adding a generated voice preview to the permanent library.

```python
def create_voice_from_preview(
    generated_voice_id: str,
    voice_name: str,
    voice_description: str,
) -> TextContent
```

--------------------------------

### play_audio(input_file_path: str)

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/models-and-info.md

Plays an audio file from the specified path using the server's audio output device. This is a synchronous operation that blocks until playback completes.

```APIDOC
## play_audio

### Description
Plays an audio file directly using the server's audio output device. Supports WAV and MP3 formats.

### Signature
`def play_audio(input_file_path: str) -> TextContent`

### Parameters
- **input_file_path** (str) - Required - Path to the audio file to play. Must be absolute or relative to `ELEVENLABS_MCP_BASE_PATH`.

### Return Type
`TextContent` - Success message containing confirmation of playback and the file path played.

### Usage Example
```python
# Play a generated TTS file
result = play_audio(input_file_path="/path/to/generated_speech.mp3")
```

### Requirements
- Server must have audio output device available
- File must exist and be readable
- Format must be WAV or MP3
```

--------------------------------

### Define try_find_similar_files function

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Defines the signature for finding audio/video files in a directory with extension filtering.

```python
def try_find_similar_files(
    filename: str,
    directory: Path,
    take_n: int = 5
) -> list[Path]
```

--------------------------------

### Remix with New Sections Workflow

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/music-inpainting.md

Combines generated sections with original audio segments to create a remixed composition.

```python
# Use uploaded track as inspiration/conditioning
composition_plan = {
    "chunks": [
        {
            "text": "Remixed intro with modern production",
            "duration_ms": 15000,
            "positive_styles": ["modern", "electronic"],
            "conditioning_ref": "song_xyz789abc123",
            "condition_strength": 0.6
        },
        {
            "type": "AudioRefChunk",
            "song_id": "song_xyz789abc123",
            "range": {"start_ms": 10000, "end_ms": 35000}  # Original verse
        },
        {
            "text": "New chorus with contemporary production",
            "duration_ms": 20000,
            "positive_styles": ["modern", "pop"],
            "context_adherence": 0.8
        }
    ]
}

result = compose_music(composition_plan=composition_plan)
```

--------------------------------

### Create an EmbeddedResource response

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Demonstrates creating an EmbeddedResource, which automatically handles base64 encoding for binary data.

```python
audio_bytes = b"\xff\xfb..."  # MP3 data
resource = create_resource_response(
    audio_bytes,
    "output.mp3",
    "mp3",
    Path("/home/user/audio")
)
# Returns: EmbeddedResource with base64-encoded audio
```

--------------------------------

### Locate uvx executable

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/README.md

Find the absolute path for uvx to resolve ENOENT errors in MCP configuration.

```bash
which uvx
```

--------------------------------

### Configure Output Modes in claude_desktop_config.json

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/README.md

Environment variable configurations for controlling how the MCP server handles generated file outputs.

```json
"env": {
  "ELEVENLABS_API_KEY": "your-api-key",
  "ELEVENLABS_MCP_OUTPUT_MODE": "files"
}
```

```json
"env": {
  "ELEVENLABS_API_KEY": "your-api-key",
  "ELEVENLABS_MCP_OUTPUT_MODE": "resources"
}
```

```json
"env": {
  "ELEVENLABS_API_KEY": "your-api-key",
  "ELEVENLABS_MCP_OUTPUT_MODE": "both"
}
```

--------------------------------

### Handle multiple files output mode in Python

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Defines the function signature for processing results from multiple handle_output_mode calls.

```python
def handle_multiple_files_output_mode(
    results: list[Union[TextContent, EmbeddedResource]],
    output_mode: str,
    additional_info: str = None
) -> Union[TextContent, list[EmbeddedResource]]
```

--------------------------------

### Handle output mode in Python

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/utilities.md

Defines the function signature for handling file output based on the configured mode.

```python
def handle_output_mode(
    file_data: bytes,
    output_path: Path,
    filename: str,
    output_mode: str,
    success_message: str = None
) -> Union[TextContent, EmbeddedResource]
```

--------------------------------

### Clone a voice

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/voice-management.md

Creates an instant voice clone from a list of audio files. Requires at least one file and a unique name.

```python
def voice_clone(
    name: str,
    files: list[str],
    description: str | None = None,
) -> TextContent
```

```python
result = voice_clone(
    name="John Custom Voice",
    files=["/path/to/sample1.wav", "/path/to/sample2.wav"],
    description="Custom voice trained on John's voice samples"
)
# Returns: TextContent with created voice details and ID
```

--------------------------------

### Text-to-speech with custom output directory

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/api-reference/text-to-speech.md

Specifies a custom file system path for saving the generated audio file.

```python
result = text_to_speech(
    text="Save this to a custom location.",
    voice_name="Sarah",
    output_directory="/path/to/audio/files"
)
```

--------------------------------

### Handle Directory Not Writeable Error

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/errors.md

Triggered when the output directory lacks the necessary write permissions.

```python
# Raises: ElevenLabsMcpError("Directory (/root/protected) is not writeable")
text_to_speech(text="Hello", output_directory="/root/protected")
```

--------------------------------

### Define Optional Fields

Source: https://github.com/elevenlabs/elevenlabs-mcp/blob/main/_autodocs/types.md

Shows the syntax for optional parameters that default to None.

```python
voice_id: str | None = None  # Optional, defaults to None
```