十一实验室-MCP

<div class="title-block" style="text-align: center;" align="center">

</div> <p align="center"> 正式的 ElevenLabs <a href="https://github.com/modelcontextprotocol">模型上下文协议（MCP）</a> 服务器，支持与强大的文本转语音和音频处理API进行交互。此服务器允许像 <a href="https://www.anthropic.com/claude">Claude Desktop</a>、<a href="https://www.cursor.so">Cursor</a>、<a href="https://codeium.com/windsurf">Windsurf</a>、<a href="https://github.com/openai/openai-agents-python">OpenAI Agents</a> 等MCP客户端生成语音、克隆声音、转录音频等。 </p> <!-- mcp-name: io.github.elevenlabs/elevenlabs-mcp -->

使用 Claude Desktop 快速开始

1. 从 ElevenLabs 获取你的API密钥。有一个免费层级，每月提供10K信用额度。
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": "<在此插入您的API密钥>"
      }
    }
  }
}

如果你使用的是Windows，你需要在 Claude Desktop 中启用“开发者模式”。点击左上角的汉堡菜单中的“帮助”，然后选择“启用开发者模式”。

其他 MCP 客户端

对于其他客户端如 Cursor 和 Windsurf，运行：

1. pip install elevenlabs-mcp
2. python -m elevenlabs_mcp --api-key={{在此插入您的API密钥}} --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"
   }
   

资源模式的好处：

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

使用案例：

• 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
# 编辑 .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

故障排除

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

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

使用某些工具时超时

某些ElevenLabs API操作，如声音设计和音频隔离，可能需要很长时间才能完成。当在开发模式下使用MCP检查器时，尽管工具完成了预期的任务，你可能会遇到超时错误。

这在使用像Claude这样的客户端时不应发生。

MCP ElevenLabs: spawn uvx ENOENT

如果你遇到错误 "MCP ElevenLabs: spawn uvx ENOENT"，请通过运行以下命令确认其绝对路径：

which uvx

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