ElevenLabs MCP Server

Official ElevenLabs Model Context Protocol (MCP) server that enables interaction with powerful Text to Speech and audio processing APIs. This server allows MCP clients like Claude Desktop, Cursor, Windsurf, OpenAI Agents and others to generate speech, clone voices, transcribe audio, and more.

快速入门Claude桌面版

1. 从以下位置获取您的API密钥 ElevenLabs（注：这是一个假设或特定的公司或项目名称，直接翻译为中文可能无直接对应词汇，故保留原英文形式，若需意译，可根据上下文具体情境，如意为“十一实验室”或“十一语音科技”等，但此处提供最直接的翻译形式）有一个免费套餐，每月提供1万积分。
2. 安装 uv (Python包管理器)，使用以下命令安装： curl -LsSf https://astral.sh/uv/install.sh | sh 或者查看 uv 仓库 以获取其他安装方法。
3. 前往 Claude > 设置 > 开发者 > 编辑配置 > 编辑 claude_desktop_config.json 文件，并添加以下内容：

{
  "mcpServers": {
    "ElevenLabs": {
      "command": "uvx",
      "args": ["elevenlabs-mcp"],
      "env": {
        "ELEVENLABS_API_KEY": ""
      }
    }
  }
}

如果你使用的是Windows系统，你需要在Claude Desktop中启用“开发者模式”才能使用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 的积分。

试试问克劳德：

• “创建一个能像黑色电影中的侦探一样说话，并能回答有关经典电影问题的AI代理”
• “为一位智慧的古老龙角色生成三种不同的声音变体，然后我会选择我最喜欢的声音加入到我的声音库中。”
• “把我这段录音的声音转换成听起来像中世纪骑士的那样”
• “创作一个密林中雷雨交加的声音景观，让动物们对天气做出反应”
• “将这段语音转换成文字，识别出不同的说话者，然后为每个人使用独特的声音将其转换回语音”

可选功能

文件输出配置

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

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

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

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

1. 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

1. 创建一个虚拟环境并安装依赖项 使用紫外线:

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桌面端安装服务器： mcp install elevenlabs_mcp/server.py

1. 使用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"）。 这确保引用了正确的可执行文件。