elevenlabs-mcp

Claude Desktop 快速入门

1. 从 ElevenLabs 获取您的 API 密钥。提供每月 1 万字符额度的免费层级。

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 中启用“开发者模式”才能使用 MCP 服务器。点击左上角汉堡菜单中的“Help”，然后选择“Enable Developer Mode”。

Related MCP server: ElevenLabs MCP Server

其他 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 代理，说话像黑色电影中的侦探，并且能回答关于经典电影的问题”

• “为睿智的远古巨龙角色生成三种语音变体，然后我将选择我最喜欢的语音添加到我的语音库中”

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

• “创建一个茂密丛林中雷雨的声音景观，并配上动物对天气的反应”

• “将这段语音转为文本，识别不同的说话者，然后使用每个人独特的语音将其转换回来”

可选功能

文件输出配置

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

• ELEVENLABS_MCP_BASE_PATH：指定相对路径文件操作的基准路径（默认：~/Desktop）

• 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"
   }

资源模式的优势：

• 文件直接在 MCP 响应中以 base64 编码数据返回

• 无需磁盘 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"）。这确保引用了正确的执行文件。