Skip to main content
Glama
ElevenLabs MCP Server

ElevenLabs MCP Server

Official
by elevenlabs

出口

Discord 社区 叽叽喳喳 PyPI 测试

使用 Claude Desktop 快速入门

  1. 从ElevenLabs获取 API 密钥。我们提供每月 10,000 积分的免费套餐。

  2. 安装uv (Python 包管理器),使用curl -LsSf https://astral.sh/uv/install.sh | sh安装,或查看uvrepo以了解其他安装方法。

  3. 转到 Claude > 设置 > 开发人员 > 编辑配置 > claude_desktop_config.json 以包含以下内容:

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

如果您使用的是 Windows,则必须在 Claude Desktop 中启用“开发者模式”才能使用 MCP 服务器。点击左上角汉堡菜单中的“帮助”,然后选择“启用开发者模式”。

Related MCP server: elevenlabs-mcp

其他 MCP 客户端

对于 Cursor 和 Windsurf 等其他客户端,请运行:

  1. pip install elevenlabs-mcp

  2. python -m elevenlabs_mcp --api-key={{PUT_YOUR_API_KEY_HERE}} --print获取配置。将其粘贴到 MCP 客户端指定的相应配置目录中。

就这样。您的 MCP 客户端现在可以通过以下工具与 ElevenLabs 进行交互:

示例用法

⚠️ 警告:使用这些工具需要 ElevenLabs 积分。

尝试询问克劳德:

  • “创建一个像黑色电影侦探一样说话并能回答有关经典电影的问题的人工智能代理”

  • “为一个睿智的古代巨龙角色生成三种不同的声音,然后我会选择我最喜欢的声音添加到我的语音库中”

  • “将我的录音转换成中世纪骑士的声音”

  • “创造茂密丛林中雷雨的音景,并让动物对天气做出反应”

  • “将这段演讲转换成文本,识别不同的说话者,然后使用每个人独特的声音将其转换回来”

可选功能

您可以将ELEVENLABS_MCP_BASE_PATH环境变量添加到claude_desktop_config.json中,以指定 MCP 服务器应查找的基本路径以及输出使用相对路径指定的文件。

贡献

如果您想贡献或从源代码运行:

  1. 克隆存储库:

git clone https://github.com/elevenlabs/elevenlabs-mcp
cd elevenlabs-mcp
  1. 使用 uv创建虚拟环境并安装依赖项:

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
  1. 将.env.example复制到.env并添加您的 ElevenLabs API 密钥:

cp .env.example .env
# Edit .env and add your API key
  1. 运行测试以确保一切正常:

./scripts/test.sh
# Or with options
./scripts/test.sh --verbose --fail-fast
  1. 在 Claude Desktop 中安装服务器: mcp install elevenlabs_mcp/server.py

  2. 使用 MCP Inspector 在本地进行调试和测试: mcp dev elevenlabs_mcp/server.py

故障排除

使用 Claude Desktop 运行时的日志可以在以下位置找到:

  • Windows : %APPDATA%\Claude\logs\mcp-server-elevenlabs.log

  • macOS : ~/Library/Logs/Claude/mcp-server-elevenlabs.log

使用某些工具时超时

某些 ElevenLabs API 操作(例如语音设计和音频隔离)可能需要很长时间才能解决。在开发模式下使用 MCP 检查器时,即使该工具已完成其预期任务,您仍可能会遇到超时错误。

使用像 Claude 这样的客户端时不应该发生这种情况。

MCP ElevenLabs:生成 uvx ENOENT

如果遇到错误“MCP ElevenLabs:spawn uvx ENOENT”,请在终端中运行以下命令确认其绝对路径:

which uvx

获取绝对路径(例如/usr/local/bin/uvx )后,请更新配置以使用该路径(例如"command": "/usr/local/bin/uvx" )。这可确保引用正确的可执行文件。

Available Tools

27 tools
add_knowledge_base_to_agentA

Add a knowledge base to ElevenLabs workspace. Allowed types are epub, pdf, docx, txt, html.

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

Args:
    agent_id: ID of the agent to add the knowledge base to.
    knowledge_base_name: Name of the knowledge base.
    url: URL of the knowledge base.
    input_file_path: Path to the file to add to the knowledge base.
    text: Text to add to the knowledge base.

Inputs: agent_id (required), knowledge_base_name (required), url, text, +1 more. Returns: Text content for a message.

check_subscriptionA
Read-only

Check the current subscription status. Could be used to measure the usage of the API.

Inputs: no named parameters. Returns: Text content for a message.

compose_musicA
Read-only

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. Saves output file to directory (default: $HOME/Desktop).

Two models are supported:
- music_v2 (default): latest model. Composition plans use a `chunks` array where each chunk is either a `GenerationChunk` (text, duration_ms, positive_styles, negative_styles, context_adherence, optional conditioning_ref + condition_strength) or an `AudioRefChunk` ({song_id, range: {start_ms, end_ms}}) for inpainting. Inpainting also requires the source song to have been stored — call this tool with store_for_inpainting=True or use upload_music_for_inpainting first to get a song_id.
- music_v1: legacy model. Composition plans use positive_global_styles, negative_global_styles, sections.

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 dict. Shape depends on model_id (see above). Must provide either prompt or composition_plan.
    music_length_ms: Length of the generated music in milliseconds (3000-600000). Cannot be used if composition_plan is provided.
    model_id: Which music model to use. One of "music_v1" or "music_v2". Defaults to "music_v2".
    force_instrumental: If True, the model will avoid generating lyrics/vocals.
    store_for_inpainting: If True, the generated song is stored server-side and the returned song_id can be used in later inpainting calls (as an AudioRefChunk.song_id, or conditioning_ref).
    seed: Optional integer seed for reproducible generation (music_v2 only).

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

Inputs: seed, prompt, model_id, music_length_ms, +4 more. Returns: result

create_agentA

Create a conversational AI agent with custom configuration.

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

Args:
    name: Name of the agent
    first_message: First message the agent will say i.e. "Hi, how can I help you today?"
    system_prompt: System prompt for the agent
    voice_id: ID of the voice to use for the agent
    language: ISO 639-1 language code for the agent
    llm: LLM to use for the agent
    temperature: Temperature for the agent. The lower the temperature, the more deterministic the agent's responses will be. Range is 0 to 1.
    max_tokens: Maximum number of tokens to generate.
    asr_quality: Quality of the ASR. `high` or `low`.
    model_id: ID of the ElevenLabs model to use for the agent.
    optimize_streaming_latency: Optimize streaming latency. Range is 0 to 4.
    stability: Stability for the agent. Range is 0 to 1.
    similarity_boost: Similarity boost for the agent. Range is 0 to 1.
    turn_timeout: Timeout for the agent to respond in seconds. Defaults to 7 seconds.
    max_duration_seconds: Maximum duration of a conversation in seconds. Defaults to 600 seconds (10 minutes).
    record_voice: Whether to record the agent's voice.
    retention_days: Number of days to retain the agent's data.

Inputs: name (required), first_message (required), system_prompt (required), llm, +13 more. Returns: Text content for a message.

create_composition_planA
Read-only

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.

The returned plan shape depends on model_id:
- music_v2 (default): `{"chunks": [GenerationChunk | AudioRefChunk, ...]}`. Each GenerationChunk has `text`, `duration_ms`, `positive_styles`, `negative_styles`, `context_adherence` and optional `conditioning_ref` + `condition_strength`. AudioRefChunks reference a stored song via `song_id` and `range: {start_ms, end_ms}` for inpainting.
- music_v1: `{"positive_global_styles": [...], "negative_global_styles": [...], "sections": [...]}`.

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 dict to use as a source for the new composition plan. Should match the shape of the model_id you request.
    model_id: Which music model to plan for. One of "music_v1" or "music_v2". Defaults to "music_v2".

Inputs: prompt (required), model_id, music_length_ms, source_composition_plan.

create_voice_from_previewA

Add a generated voice to the voice library. Uses the voice ID from the text_to_voice tool.

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

Inputs: voice_name (required), voice_description (required), generated_voice_id (required). Returns: Text content for a message.

get_agentB
Read-only

Get details about a specific conversational AI agent

Inputs: agent_id (required). Returns: Text content for a message.

get_conversationA
Read-only

Gets conversation with transcript. Returns: conversation details and full transcript. Use when: analyzing completed agent conversations.

Args:
    conversation_id: The unique identifier of the conversation to retrieve, you can get the ids from the list_conversations tool.

Inputs: conversation_id (required). Returns: Text content for a message.

get_voiceB
Read-only

Get details of a specific voice

Inputs: voice_id (required). Returns: id, name, category, fine_tuning_status

isolate_audioB
Read-only

Isolate audio from a file. Saves output file to directory (default: $HOME/Desktop).

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

Inputs: input_file_path (required), output_directory. Returns: result

list_agentsA
Read-only

List all available conversational AI agents

Inputs: no named parameters. Returns: Text content for a message.

list_conversationsA
Read-only

Lists agent conversations. Returns: conversation list with metadata. Use when: asked about conversation history.

Args:
    agent_id (str, optional): Filter conversations by specific agent ID
    cursor (str, optional): Pagination cursor for retrieving next page of results
    call_start_before_unix (int, optional): Filter conversations that started before this Unix timestamp
    call_start_after_unix (int, optional): Filter conversations that started after this Unix timestamp
    page_size (int, optional): Number of conversations to return per page (1-100, defaults to 30)
    max_length (int, optional): Maximum character length of the response text (defaults to 10000)

Inputs: cursor, agent_id, page_size, max_length, +2 more. Returns: Text content for a message.

list_modelsB
Read-only

List all available models

Inputs: no named parameters. Returns: result

list_phone_numbersA
Read-only

List all phone numbers associated with the ElevenLabs account

Inputs: no named parameters. Returns: Text content for a message.

make_outbound_callA
Destructive

Make an outbound call using an ElevenLabs agent. Automatically detects provider type (Twilio or SIP trunk) and uses the appropriate API.

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

Args:
    agent_id: The ID of the agent that will handle the call
    agent_phone_number_id: The ID of the phone number to use for the call
    to_number: The phone number to call (E.164 format: +1xxxxxxxxxx)

Returns:
    TextContent containing information about the call

Inputs: agent_id (required), to_number (required), agent_phone_number_id (required). Returns: Text content for a message.

play_audioB
Read-only

Play an audio file. Supports WAV and MP3 formats.

Inputs: input_file_path (required). Returns: Text content for a message.

search_voice_libraryA
Read-only

Search for a voice across the entire ElevenLabs voice library.

Args:
    page: Page number to return (0-indexed)
    page_size: Number of voices to return per page (1-100)
    search: Search term to filter voices by

Returns:
    TextContent containing information about the shared voices

Inputs: page, search, page_size. Returns: Text content for a message.

search_voicesA
Read-only
Search for existing voices, a voice that has already been added to the user's ElevenLabs voice library.
Searches in name, description, labels and category.

Args:
    search: Search term to filter voices by. Searches in name, description, labels and category.
    sort: Which field to sort by. `created_at_unix` might not be available for older voices.
    sort_direction: Sort order, either ascending or descending.

Returns:
    List of voices that match the search criteria.

Inputs: sort, search, sort_direction. Returns: result

simulate_conversationA

Simulate a text conversation between a conversational AI agent and a simulated user. Runs the full conversation and returns the transcript plus analysis.

Use this to test agent behaviour, evaluate prompts, and catch failure modes without
a live call. The simulated user follows the persona you describe.

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

Args:
    agent_id: ID of the agent to test. Use list_agents to find IDs.
    simulated_user_prompt: Instructions for how the simulated user should behave.
        Example: "You are a frustrated customer who cannot find the cancel button."
    first_message: Optional opening message to kick off the conversation.
    extra_evaluation_criteria: Optional list of dicts, each with:
        - id (str): unique key e.g. "issue_resolved"
        - name (str): human label e.g. "Issue Resolved"
        - conversation_goal_prompt (str): the assertion to check
          e.g. "The agent fully resolved the user's issue."
        - use_knowledge_base (bool, optional): whether the evaluator should
          reference the agent's knowledge base when judging. Defaults to False.
    max_turns: Maximum conversation turns. Defaults to 10.

Inputs: agent_id (required), simulated_user_prompt (required), max_turns, first_message, +1 more. Returns: Text content for a message.

speech_to_speechB
Read-only

Transform audio from one voice to another using provided audio files. Saves output file to directory (default: $HOME/Desktop).

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

Inputs: input_file_path (required), voice_name, output_directory. Returns: result

speech_to_textA
Read-only

Transcribe speech from an audio file. When save_transcript_to_file=True: Saves output file to directory (default: $HOME/Desktop). When return_transcript_to_client_directly=True, always returns text directly regardless of output mode.

⚠️ 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 (only used when saving files).
        Defaults to $HOME/Desktop if not provided.

Returns:
    TextContent containing the transcription or MCP resource with transcript data.

Inputs: input_file_path (required), diarize, language_code, output_directory, +2 more. Returns: result

text_to_sound_effectsA
Read-only

Convert text description of a sound effect to sound effect with a given duration. Saves output file to directory (default: $HOME/Desktop).

Duration must be between 0.5 and 5 seconds.

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

Args:
    text: Text description of the sound effect
    duration_seconds: Duration of the sound effect in seconds
    output_directory: Directory where files should be saved (only used when saving files).
        Defaults to $HOME/Desktop if not provided.
    loop: Whether to loop the sound effect. Defaults to False.
    output_format (str, optional): Output format of the generated audio. Formatted as codec_sample_rate_bitrate. So an mp3 with 22.05kHz sample rate at 32kbs is represented as mp3_22050_32. MP3 with 192kbps bitrate requires you to be subscribed to Creator tier or above. PCM with 44.1kHz sample rate requires you to be subscribed to Pro tier or above. Note that the μ-law format (sometimes written mu-law, often approximated as u-law) is commonly used for Twilio audio inputs.
        Defaults to "mp3_44100_128". Must be one of:
        mp3_22050_32
        mp3_44100_32
        mp3_44100_64
        mp3_44100_96
        mp3_44100_128
        mp3_44100_192
        pcm_8000
        pcm_16000
        pcm_22050
        pcm_24000
        pcm_44100
        ulaw_8000
        alaw_8000
        opus_48000_32
        opus_48000_64
        opus_48000_96
        opus_48000_128
        opus_48000_192

Inputs: text (required), loop, output_format, duration_seconds, +1 more. Returns: result

text_to_speechA
Read-only

Convert text to speech with a given voice. Saves output file to directory (default: $HOME/Desktop).

Only one of voice_id or voice_name can be provided. If none are provided, the default voice will be used.

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

 Args:
    text (str): The text to convert to speech.
    voice_name (str, optional): The name of the voice to use.
    model_id (str, optional): The model ID to use for speech synthesis. Options include:
        - eleven_v3: High quality model with most expressive voices
        - eleven_multilingual_v2: High quality multilingual model (29 languages)
        - eleven_flash_v2_5: Fastest model with ultra-low latency (32 languages)
        - eleven_turbo_v2_5: Balanced quality and speed (32 languages)
        - eleven_flash_v2: Fast English-only model
        - eleven_turbo_v2: Balanced English-only model
        Defaults to eleven_multilingual_v2 or environment variable ELEVENLABS_MODEL_ID.
    stability (float, optional): Stability of the generated audio. Determines how stable the voice is and the randomness between each generation. Lower values introduce broader emotional range for the voice. Higher values can result in a monotonous voice with limited emotion. Range is 0 to 1.
    similarity_boost (float, optional): Similarity boost of the generated audio. Determines how closely the AI should adhere to the original voice when attempting to replicate it. Range is 0 to 1.
    style (float, optional): Style of the generated audio. Determines the style exaggeration of the voice. This setting attempts to amplify the style of the original speaker. It does consume additional computational resources and might increase latency if set to anything other than 0. Range is 0 to 1.
    use_speaker_boost (bool, optional): Use speaker boost of the generated audio. This setting boosts the similarity to the original speaker. Using this setting requires a slightly higher computational load, which in turn increases latency.
    speed (float, optional): Speed of the generated audio. Controls the speed of the generated speech. Values range from 0.7 to 1.2, with 1.0 being the default speed. Lower values create slower, more deliberate speech while higher values produce faster-paced speech. Extreme values can impact the quality of the generated speech. Range is 0.7 to 1.2.
    output_directory (str, optional): Directory where files should be saved (only used when saving files).
        Defaults to $HOME/Desktop if not provided.
    language: ISO 639-1 language code for the voice.
    output_format (str, optional): Output format of the generated audio. Formatted as codec_sample_rate_bitrate. So an mp3 with 22.05kHz sample rate at 32kbs is represented as mp3_22050_32. MP3 with 192kbps bitrate requires you to be subscribed to Creator tier or above. PCM with 44.1kHz sample rate requires you to be subscribed to Pro tier or above. Note that the μ-law format (sometimes written mu-law, often approximated as u-law) is commonly used for Twilio audio inputs.
        Defaults to "mp3_44100_128". Must be one of:
        mp3_22050_32
        mp3_44100_32
        mp3_44100_64
        mp3_44100_96
        mp3_44100_128
        mp3_44100_192
        pcm_8000
        pcm_16000
        pcm_22050
        pcm_24000
        pcm_44100
        ulaw_8000
        alaw_8000
        opus_48000_32
        opus_48000_64
        opus_48000_96
        opus_48000_128
        opus_48000_192

Returns:
    Text content with file path or MCP resource with audio data, depending on output mode.

Inputs: text (required), speed, style, language, +8 more. Returns: result

text_to_voiceB
Read-only

Create voice previews from a text prompt. Creates three previews with slight variations. Saves output file to directory (default: $HOME/Desktop).

If no text is provided, the tool will auto-generate text.

Voice preview files are saved as: voice_design_(generated_voice_id)_(timestamp).mp3

Example file name: voice_design_Ya2J5uIa5Pq14DNPsbC1_20250403_164949.mp3

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

Inputs: voice_description (required), text, output_directory. Returns: result

upload_music_for_inpaintingA

Upload an existing audio file to ElevenLabs so it can be referenced in music_v2 inpainting workflows. Returns a song_id you can plug into a composition plan's AudioRefChunks (or a generation chunk's conditioning_ref) to edit or extend the track via the compose_music tool.

Optionally extracts a composition plan from the uploaded audio so you have a starting point to mutate.

Note: this endpoint is gated to enterprise customers with inpainting access.

Args:
    input_file_path: Path to a local audio file to upload.
    extract_composition_plan: Which model to extract a composition plan for ("music_v1" or "music_v2"). Pass None to skip extraction. Defaults to "music_v2".

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

Inputs: input_file_path (required), extract_composition_plan. Returns: Text content for a message.

video_to_musicA
Read-only

Generate background music for one or more video files. Saves output file to directory (default: $HOME/Desktop).

The videos are concatenated server-side in the order provided; the generated score targets the combined duration. Constraints: 1-10 videos per call, combined size <= 200 MB, combined duration <= 600 seconds.

Args:
    input_file_paths: Paths to the video files. Order is preserved.
    description: Optional natural-language direction for the music (e.g. "Build suspense, then resolve with a warm cinematic finish.").
    tags: Optional list of up to 10 short style cues (e.g. ["cinematic", "suspenseful", "uplifting"]).
    model_id: Which music model to use. One of "music_v1" or "music_v2". Defaults to "music_v2".
    output_directory: Directory to save the generated audio file. Defaults to $HOME/Desktop.

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

Inputs: input_file_paths (required), tags, model_id, description, +1 more. Returns: result

voice_cloneB

Create an instant voice clone of a voice using provided audio files.

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

Inputs: name (required), files (required), description. Returns: Text content for a message.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 27 tools

    Disambiguation3/5

    Some tools have clear boundaries, but several pairs are easy to confuse: search_voices vs search_voice_library, text_to_voice vs text_to_speech, and video_to_music vs compose_music. The detailed descriptions help, but an agent could easily misselect between the voice-related and music-generation tools.

    Naming Consistency4/5

    Most tools follow a clean snake_case pattern with common prefixes like list_, get_, and create_. Minor deviations like voice_clone (noun-verb instead of verb-noun) and the text_to_*/speech_to_* transformation names break the uniformity slightly, but the overall convention is predictable.

    Tool Count3/5

    27 tools is on the heavy side, especially with multiple music and voice tools that could potentially be consolidated. However, the server spans several distinct ElevenLabs product areas (speech, music, voices, agents, phone calls), so the count is defensible for a broad platform API server.

    Completeness3/5

    The surface covers core generation workflows well: TTS, STT, music, sound effects, voice cloning, agents, and conversations. Notable gaps exist in lifecycle management: create_agent has no update_agent/delete_agent, voice creation lacks delete_voice, and add_knowledge_base_to_agent has no corresponding list/remove tool.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers