官方 ElevenLabs 模型上下文协议 (MCP) 服务器

export

Discord Community
Twitter
PyPI
Tests

官方 ElevenLabs 模型上下文协议 (MCP) 服务器，旨在实现与强大的文本转语音 (TTS) 及音频处理 API 的交互。该服务器使得诸如 Claude Desktop、Cursor、Windsurf、OpenAI Agents 等 MCP 客户端能够生成语音、克隆声音、转录音频以及执行更多操作。

1- 使用 Claude Desktop 快速入门

  1. 访问 ElevenLabs 获取您的 API 密钥。我们提供免费套餐，每月包含 10,000 点积分。
  2. 安装 uv (一个 Python 包管理器)：使用 curl -LsSf https://astral.sh/uv/install.sh | sh 命令安装，或查阅 uv 的 GitHub 仓库 了解其他安装方式。
  3. 在 Claude Desktop 中，导航至 " 设置 " > " 开发者 " > " 编辑配置 "，打开 claude_desktop_config.json 文件，并添加以下配置：
{
  "mcpServers": {
    "ElevenLabs": {
      "command": "uvx",
      "args": ["elevenlabs-mcp"],
      "env": {
        "ELEVENLABS_API_KEY": "<在此处粘贴您的 API 密钥>"
      }
    }
  }
}

1.1- Windows

如果您使用 Windows 系统，需要在 Claude Desktop 中启用 " 开发者模式 " 才能使用 MCP 服务器。

  • 请点击左上角的汉堡菜单（≡），选择 " 帮助 "，然后点击 " 启用开发者模式 "。

2- 其他 MCP 客户端

对于 Cursor、Windsurf 等其他客户端，请执行以下步骤：

  1. 安装包：pip install elevenlabs-mcp
  2. 获取配置信息：
    1. 运行 python -m elevenlabs_mcp --api-key={{在此处填入您的 API 密钥}} --print。
    2. 将输出的配置信息粘贴到您的 MCP 客户端指定的配置目录中。

配置完成后，您的 MCP 客户端即可通过以下工具与 ElevenLabs 进行交互：

3- 使用示例

⚠️ 注意：使用这些工具会消耗 ElevenLabs 积分。

您可以尝试向 Claude 发出以下指令：

  • " 创建一个 AI 代理，让它用黑色电影侦探的口吻说话，并能回答关于经典老电影的问题。"
  • " 为一个充满智慧的远古巨龙角色生成三种不同的声音样本，供我选择最喜欢的一种加入到我的声音库。"
  • " 将这段我的录音转换成中世纪骑士的音色。"
  • " 创作一个音景：茂密丛林中的雷雨声，以及动物们对天气的反应。"
  • " 将这段语音转换成文字，识别出不同的说话人，然后为每个人分配独特的声音，再转换回语音。"

4- 可选功能

您可以将 ELEVENLABS_MCP_BASE_PATH 环境变量添加到 claude_desktop_config.json 的 env 部分。这用于指定 MCP 服务器在处理相对路径时，应该在哪里查找输入文件以及输出文件。

5- 贡献代码

如果您希望参与贡献或从源代码运行本项目：

  1. 克隆仓库：

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

  2. 创建 Python 虚拟环境并安装依赖（推荐 使用 uv）：

    uv venv
source .venv/bin/activate  # macOS/Linux
# 或者 .venv\Scripts\activate  # Windows
uv pip install -e ".[dev]"

  3. 复制 .env.example 文件为 .env，并在 .env 文件中填入您的 ElevenLabs API 密钥：

    cp .env.example .env
# 编辑 .env 文件，添加您的 API 密钥

  4. 运行测试，确保所有功能正常：

    ./scripts/test.sh
# 或者附加选项运行
./scripts/test.sh --verbose --fail-fast

  5. 在 Claude Desktop 中安装本地服务器： mcp install elevenlabs_mcp/server.py

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

6- 故障排查

当通过 Claude Desktop 运行时，相关的日志文件位于：

  • Windows: %APPDATA%\Claude\logs\mcp-server-elevenlabs.log
  • macOS: ~/Library/Logs/Claude/mcp-server-elevenlabs.log

6.1- 使用特定工具时可能出现的超时问题

部分 ElevenLabs API 操作（例如声音设计、音频分离等）可能需要较长时间处理。当您在开发模式下使用 MCP Inspector 进行测试时，可能会遇到超时错误，但这通常不影响工具最终完成其任务。

在实际的客户端（如 Claude Desktop）中使用时，一般不会出现此类超时中断问题。

主要优化点：

  1. 术语和表达：

    • 将 “interaction with” 翻译为更自然的 " 实现与…的交互 "。
    • 将 “Text to Speech” 明确标注为 “(TTS)”。
    • 将 “allows … clients … to generate” 调整为 " 使得 … 客户端能够生成…"，更流畅。
    • 将 “Get your API key” 调整为 " 访问 … 获取您的 API 密钥 "。
    • 将 “credits” 统一翻译为 " 积分 "，并在首次提到时说明数量 "10,000 点积分 "。
    • 将 “Go to … to include the following” 调整为 " 导航至 … 打开 … 文件，并添加以下配置 "。
    • 将 “hamburger menu” 更清晰地描述为 " 汉堡菜单（≡）"。
    • 将 “run:” 调整为更自然的 " 请执行以下步骤：" 或 " 获取配置信息：运行…"。
    • 将 “Paste it into appropriate configuration directory” 调整为 " 将输出的配置信息粘贴到您的 MCP 客户端指定的配置目录中 "。
    • 将 “Try asking Claude:” 调整为 " 您可以尝试向 Claude 发出以下指令："。
    • 将 “Warning” 前的 Emoji 保留，文字调整为 " 注意 "。
    • 将 “Convert this recording … to sound like” 调整为 " 将这段我的录音转换成…的音色 "。
    • 将 “Turn this speech into text, …, then convert it back using unique voices” 调整为 " 将这段语音转换成文字，…，然后为每个人分配独特的声音，再转换回语音 "。
    • 将 “specify the base path … should look for and output files” 调整为 "…指定 … 在处理相对路径时，应该在哪里查找输入文件以及输出文件 "。
    • 将 “Contributing” 部分的步骤描述更清晰化，如 " 安装包：“，” 获取配置信息："。
    • 将 “Create a virtual environment and install dependencies” 中的 “dependencies” 明确为 " 依赖 "。
    • 将 “Run the tests to make sure everything is working” 调整为 " 运行测试，确保所有功能正常 "。
    • 将 “Troubleshooting” 翻译为更常用的 " 故障排查 "。
    • 将 “Logs when running with Claude Desktop can be found at:” 调整为 " 当通过 Claude Desktop 运行时，相关的日志文件位于："
    • 将 “take a long time to resolve” 调整为 " 可能需要较长时间处理 " 或 " 可能需要较长时间才能完成 "。
    • 将 “despite the tool completing its intended task” 调整为 " 但这通常不影响工具最终完成其任务 "。
    • 将 “This shouldn’t occur when using a client like Claude” 调整为 " 在实际的客户端（如 Claude Desktop）中使用时，一般不会出现此类超时中断问题 "。

  2. 格式： 保持了 Markdown 格式，包括代码块、列表、链接等。

  3. 图片路径： 确认了 ![export](…) 中的 URL 是 https://github.com/… 开头的绝对路径。