ElevenLabs MCP Server

在AI辅助创作日益普及的今天，文本的生成已经变得轻而易举，但将文字转化为自然、富有表现力的语音，仍然是内容创作中一道关键工序。无论是为视频配音、制作播客、还是有声书录制，传统的语音合成工具往往需要跳出工作流，手动上传文本、调整参数，步骤繁琐且割裂。ElevenLabs MCP Server的出现，将全球领先的AI语音合成能力，以模型上下文协议（MCP）标准的形态，直接注入了你的AI助手之中，让语音生成成为你对话的一部分。

项目基本信息

一、项目介绍

ElevenLabs MCP Server是一个桥梁，它通过MCP协议，将ElevenLabs强大的文本转语音能力，以标准化的工具、资源和提示形式，暴露给支持MCP的AI客户端，如Claude Desktop、Cursor等。

核心能力解析

这个服务器提供了一套完整的语音生成管理工具集：

• generate_audio_simple：最直接的文本转语音工具。你只需提供文本，它就会使用默认或预设的声音参数，快速生成音频文件。适合快速旁白、简单的语音提示等场景。
• generate_audio_script：这是为深度创作准备的高级工具。它接受一个结构化的脚本，脚本中可以指定多个“演员”和各自的台词，每个“演员”可以使用不同的ElevenLabs声音。这使得生成对话、多角色剧本等复杂音频内容成为可能。
• list_voices：一个辅助管理工具，让你（或你的AI助手）能够查询ElevenLabs账户下所有可用的声音模型，以便选择最合适的音色。
• get_voiceover_history与get_audio_file：用于检索过去的生成作业历史和下载已生成的音频文件，方便内容管理和回顾。
• delete_job：可以按ID删除历史上的生成作业。

此外，服务器还通过MCP资源(Resources)机制暴露了voiceover://history/{job_id}和voiceover://voices两个端点，允许客户端以结构化的方式直接获取音频和历史数据。

二、核心优势

顶级语音AI能力的无缝集成

这是ElevenLabs MCP Server最核心的价值。ElevenLabs本身就是AI语音合成领域的佼佼者，以其自然、富有情感和高度可定制的声音而闻名。通过MCP，你不需要离开你的聊天或编码环境，只需一个指令，你的AI助手就能帮你完成高质量的语音生成。

简单与复杂的兼顾

generate_audio_simple和generate_audio_script两个核心工具的设计非常精巧。一个满足“一句话生成语音”的快捷需求，另一个则为“多角色、多声音的完整剧本”提供了结构化的解决方案，覆盖了从轻量使用到专业创作的不同场景。

完善的管理链条

项目不仅关注“生成”，还关注“管理”。通过历史记录查询、音频文件获取和作业删除等功能，它提供了围绕音频资产的完整管理闭环，这在很多同类工具中并不常见。

灵活的部署与开发

项目支持通过uvx一键安装配置，极大降低了使用门槛。同时，它也提供了详细的本地开发指南，并附带一个基于SvelteKit的示例Web客户端，为希望进行二次开发或部署Web服务的开发者提供了极佳的起点。

三、适用场景

AI辅助的内容创作与配音

你可以让Claude或Cursor帮你写一篇博客文章，然后直接指示它：“将这篇文章用自然的女声朗读出来，生成一个MP3文件。”AI会调用generate_audio_simple完成操作，你立刻就能获得文章的音频版本。

播客与多人剧本制作

利用generate_audio_script，你可以构思一个有两个主持人对谈的播客片段，将不同的台词分配给“主持人A”和“主持人B”，并为他们指定不同的ElevenLabs声音，直接生成一个多人对话的音频文件。

多语言学习与有声书制作

对于语言学习者，可以生成特定语言的例句发音，用于跟读模仿。对于有声书制作者，可以通过脚本工具，为书中的不同角色分配不同的声音，高效制作分角色的有声内容。

自动化音频工作流

开发者可以将此MCP服务器集成到更大的自动化流水线中。例如，一个自动化的新闻简报系统，在抓取和总结新闻后，可以自动调用ElevenLabs MCP服务器将摘要转为音频，并通过邮件或消息发送给订阅者。

四、安装教程

环境要求

获取ElevenLabs API密钥

1. 访问 ElevenLabs官网 并注册/登录账户。
2. 进入个人Profile或API Keys管理页面，创建一个新的API Key并妥善保存。

通过uvx安装（推荐）

这是最简便的方法，无需手动克隆仓库。在你的MCP客户端配置文件中，直接添加以下配置即可。

Claude Desktop 配置示例
编辑以下路径的JSON配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "elevenlabs": {
      "command": "uvx",
      "args": ["elevenlabs-mcp-server"],
      "env": {
        "ELEVENLABS_API_KEY": "your-api-key",
        "ELEVENLABS_VOICE_ID": "your-default-voice-id",
        "ELEVENLABS_MODEL_ID": "eleven_flash_v2",
        "ELEVENLABS_OUTPUT_DIR": "output"
      }
    }
  }
}

环境变量说明：

• ELEVENLABS_API_KEY：你的ElevenLabs API密钥（必填）。
• ELEVENLABS_VOICE_ID：默认使用的声音ID，可在ElevenLabs声音库中查找。
• ELEVENLABS_MODEL_ID：推荐的模型是eleven_flash_v2，速度更快成本更低；更高质量可选eleven_multilingual_v1。
• ELEVENLABS_STABILITY、ELEVENLABS_SIMILARITY_BOOST、ELEVENLABS_STYLE：声音的精细调优参数，可根据需要调整（0到1之间的小数）。
• ELEVENLABS_OUTPUT_DIR：生成音频的输出目录。

配置完成后，保存文件并完全重启你的MCP客户端。

备选方案：通过Smithery安装

npx -y @smithery/cli install elevenlabs-mcp-server --client claude

本地开发安装

1. 克隆仓库

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

2. 创建虚拟环境并安装依赖

   uv venv
   source .venv/bin/activate  # macOS/Linux
   .venv\Scripts\activate     # Windows

3. 配置环境变量
   复制 .env.example 为 .env，并填入你的ElevenLabs凭证。
4. 在MCP客户端中配置
   使用“开发安装”部分的JSON配置，将command和args指向你的本地Python环境和项目路径。

五、使用示例

配置成功后，你可以在AI客户端中使用自然语言指挥AI完成语音生成。

示例一：快速文字转语音

用户指令：使用ElevenLabs，将以下文字用默认声音转为语音：“欢迎收听今天的AI早报，我是你的数字助手。”

AI的操作与回复:
AI会调用generate_audio_simple工具，传入文本。片刻之后，它会返回生成音频的文件路径或直接提供播放/下载链接。

示例二：生成多角色对话

用户指令：用ElevenLabs生成一段对话音频。脚本如下：角色A（用声音Adam）说：“今天天气真好，我们出去散步吧。”；角色B（用声音Bella）回应：“好主意，我带上相机。”

AI的操作与回复:
AI会调用generate_audio_script工具，组织如下结构化参数：

{
  "script": [
    {
      "voice_id": "voice_id_of_Adam",
      "text": "今天天气真好，我们出去散步吧。"
    },
    {
      "voice_id": "voice_id_of_Bella",
      "text": "好主意，我带上相机。"
    }
  ]
}

最终会生成一个包含两人对话的完整音频文件。

示例三：查看可用声音

用户指令：使用ElevenLabs，列出我账户下所有可用的声音模型。

AI的操作与回复:
AI会调用list_voices工具，并返回一份包含每个声音的名称、ID和样音预览链接的列表，供你选择和参考。

六、常见问题

问：配置后提示“工具未找到”或“服务器连接失败”怎么办？

答：请按以下步骤排查：

1. 检查API Key：确保ELEVENLABS_API_KEY正确无误，且账户内有可用额度。
2. 检查网络：uvx首次运行需要下载依赖包，请确保网络连接正常。如果处于代理网络环境，可能需要额外设置HTTP_PROXY环境变量。
3. 检查配置文件格式：确保JSON格式正确，特别注意env中的值都是字符串格式。

问：eleven_flash_v2和其他模型有什么区别？

答：eleven_flash_v2是ElevenLabs推出的轻量级高速模型，生成速度极快，成本较低，适合实时或大规模转换场景。如果追求极致的语音质量和情感表现力，可以使用eleven_multilingual_v1或eleven_turbo_v2_5等模型。

问：如何找到我想要的声音ID？

答：最简单的方法是让AI帮你查找。连接此服务器后，直接向AI提问：“使用ElevenLabs列出所有可用的声音”，它会调用list_voices工具，返回每个声音的ID和名称。你也可以在ElevenLabs官网上预先试听并获取。

问：生成的音频文件保存在哪里？

答：默认保存在ELEVENLABS_OUTPUT_DIR环境变量指定的目录中。如果使用uvx方式运行，该目录位于你的用户目录下或工作区中。AI在生成音频后，通常会返回文件的完整路径。

七、总结

ElevenLabs MCP Server是一座将顶级语音合成能力与你的AI创作工作流无缝连接的桥梁。它轻量、强大且易于配置，通过几个核心工具，覆盖了从简单旁白到复杂剧本配音的广泛场景。对于内容创作者、开发者以及任何希望将语音生成融入自动化流程的用户来说，这都是一个极高价值的工具。它让“用AI思考，用AI发声”成为触手可及的现实。