Elevenlabs Mcp

警告

此本地 MCP 服务已弃用，建议改用 ElevenLabs 托管 MCP 服务。

托管服务可通过 https://api.elevenlabs.io/v1/mcp 使用，无需在本地安装或运行任何内容。它通过 OAuth 进行身份验证，因此无需将 API 密钥复制到客户端中。请参阅托管 MCP 服务文档，了解如何从 Claude、Cursor 或其他 MCP 客户端进行连接。

此仓库不再积极维护。

ElevenLabs 官方 Model Context Protocol (MCP) 服务，可与强大的文本转语音和音频处理 API 交互。此服务可让 Claude Desktop、Cursor、Windsurf、OpenAI Agents 等 MCP 客户端生成语音、克隆声音、转录音频等。

使用 Claude Desktop 快速入门

1. 从 ElevenLabs 获取 API 密钥。免费套餐每月提供 10k 积分。
2. 安装 uv（Python 包管理器），可运行 curl -LsSf https://astral.sh/uv/install.sh | sh 安装，或参阅 uv 仓库了解其他安装方式。
3. 前往 Claude > Settings > Developer > Edit Config > claude_desktop_config.json，并添加以下内容：

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

如果使用 Windows，则必须在 Claude Desktop 中启用“Developer Mode”才能使用 MCP 服务。点击左上角汉堡菜单中的“Help”，然后选择“Enable Developer Mode”。

其他 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 积分。

可以尝试向 Claude 提出以下请求：

• “创建一个说话风格像黑色电影侦探、能够回答经典电影相关问题的 AI Agent”
• “为一位睿智古老的龙角色生成三种声音变体，然后我会选择最喜欢的声音添加到我的声音库中”
• “将这段我的声音录音转换成中世纪骑士的声音”
• “创建一段音景，描绘茂密丛林中的雷暴，以及动物对天气的反应”
• “将这段语音转成文字，识别不同的说话者，然后为每个人使用独特的声音转换回语音”

可选功能

文件输出配置

你可以在 claude_desktop_config.json 中使用以下环境变量，配置 MCP 服务如何处理文件输出：

• ELEVENLABS_MCP_BASE_PATH：指定文件操作的基础路径（默认值：~/Desktop）。此目录也是输入文件的安全边界：任何传递给读取本地文件的工具（例如 speech_to_text、isolate_audio、speech_to_speech、video_to_music、upload_music_for_inpainting）的路径，都必须解析到此目录内，无论提供的是绝对路径还是相对路径。目录之外的路径——即使是绝对路径且此前已被接受——也会被拒绝。请将此变量设为一个包含所有需要读取或写入内容的目录。
• ELEVENLABS_MCP_OUTPUT_MODE：控制生成的文件如何返回（默认值：files）

输出模式

环境变量 ELEVENLABS_MCP_OUTPUT_MODE 支持三种模式：

1. files（默认）：将文件保存到磁盘并返回文件路径

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

2. resources：将文件作为 MCP 资源返回；二进制数据以 base64 编码，文本以 UTF-8 文本返回

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

3. both：将文件保存到磁盘，并作为 MCP 资源返回

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

资源模式的优势：

• 文件会以 base64 编码数据的形式直接在 MCP 响应中返回
• 无需磁盘 I/O，适用于容器化或无服务器环境
• MCP 客户端无需访问文件系统即可立即获取文件内容
• 在 both 模式下，可以稍后使用 elevenlabs://filename URI 模式获取资源

适用场景：

• files：传统的基于文件的工作流、本地开发
• resources：云环境、无法访问文件系统的 MCP 客户端
• both：需要最大灵活性、缓存和资源共享的场景

数据驻留密钥

你可以使用环境变量 ELEVENLABS_API_RESIDENCY 指定数据驻留区域。默认值为 "us"。

注意： 数据驻留仅适用于企业版。更多详情请参阅文档。

贡献

如果你想参与贡献或从源代码运行：

1. 克隆代码库：

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

2. 创建虚拟环境并使用 uv安装依赖项：

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

3. 将 .env.example 复制为 .env，并添加你的 ElevenLabs API 密钥：

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

4. 运行测试，确保一切正常：

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

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

6. 使用 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 inspector 时，即使工具已完成预期任务，也可能出现超时错误。

使用 Claude 之类的客户端时，不应出现此问题。

MCP ElevenLabs：spawn uvx ENOENT

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

which uvx

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