Resemble AI Voice Generation MCP Server

类AI语音生成MCP服务器

Resemble AI语音生成 API 的服务器实现，使用模型上下文协议 (MCP) 与Claude和Cursor集成。

特征

• 使用 Resemble AI 的声音从文本生成语音音频
• 列出可用的语音模型
• 将音频作为本地文件或 base64 编码字符串返回
• 多种连接方式：
  • SSE 传输- 基于网络的服务器发送事件（默认）
  • StdIO Transport - 直接进程通信

设置说明

先决条件

• Python 3.10 或更高版本
• Resemble AI API 密钥（在Resemble AI注册）

环境设置

选项 1：使用 Conda（推荐）

选项 2：使用虚拟环境

配置

将您的 Resemble AI API 密钥设置为环境变量：

或者，在项目根目录中创建一个包含以下内容的.env文件：

运行服务器

使用运行脚本（推荐）

选择您喜欢的实施方式：

直接使用 CLI

连接到 Claude Desktop

SSE 传输连接

创建claude_desktop_config.json文件：

StdIO 传输连接

创建claude_desktop_config.json文件：

连接到光标

SSE 传输连接

1. 前往“设置”→“AI”→“MCP 服务器”
2. 点击“添加服务器”
3. 选择“SSE”作为连接类型
4. 将 URL 设置为： http://localhost:8083/sse

StdIO 传输连接

1. 前往“设置”→“AI”→“MCP 服务器”
2. 点击“添加服务器”
3. 选择“子进程”作为连接类型
4. 将命令设置为： python -m src.cli --implementation stdio
5. 可选地添加环境变量：
   • RESEMBLE_API_KEY ：您的 Resemble AI API 密钥

可用工具

list_voices

列出 Resemble AI 提供的语音模型。

generate_tts

从文本生成语音音频。

参数：

• text ：要转换为语音的文本
• voice_id ：要使用的语音的 ID
• return_type ：如何返回音频：“file”或“base64”（可选，默认值：“file”）
• output_filename ：输出的文件名（不带扩展名）（可选）

实现细节

该项目包括几个实施方案：

• src/resemble_mcp_server.py ：使用带有 SSE 传输的 MCP SDK
• src/resemble_stdio_server.py ：使用 StdIO 传输进行直接进程通信
• src/resemble_http_server.py ：使用 SSE 的 HTTP 实现（后备）
• src/resemble_ai_server.py ：直接 API 实现
• src/resemble_ai_sdk_server.py ：使用官方 Resemble SDK 实现

故障排除

MCP SDK 导入错误

如果您在导入 MCP SDK 时遇到问题，服务器将自动回退到使用 SSE 传输的 HTTP 实现。

连接问题

如果 Claude 或 Cursor 无法连接到服务器：

1. 检查服务器是否正在运行
2. 验证是否配置了正确的 URL
3. 检查您的 API 密钥是否有效
4. 在服务器日志中查找错误

StdIO 与 SSE 传输

• 当您想要单独运行服务器或在不同的机器上运行服务器时，请使用SSE Transport
• 当你希望 Claude/Cursor 为你管理服务器进程时，请使用StdIO Transport

示例

可以在examples/目录中找到示例用法。

📁 存储库结构

🚀 快速设置

提供了两个安装脚本以简化安装：

使用 Conda（推荐）

使用 Python venv

任一脚本都将：

1. 创建 Python 3.10+ 环境
2. 安装所有必需的依赖项
3. 设置模板 .env 文件
4. 创建音频文件的输出目录

手动安装

如果您希望手动设置：

1. 创建 Python 3.10+ 环境：
   # Using conda conda create -n resemble_mcp python=3.10 conda activate resemble_mcp # OR using venv (with Python 3.10+ already installed) python3.10 -m venv venv source venv/bin/activate
2. 安装依赖项：
   pip install uvicorn fastapi python-dotenv requests pydantic httpx sse-starlette pip install git+https://github.com/modelcontextprotocol/python-sdk.git
3. 设置环境变量：
   cp .env.example .env
   编辑.env文件并添加您的 Resemble AI API 密钥：
   RESEMBLE_API_KEY=your_api_key_here
   可选：自定义音频输出设置
   OUTPUT_DIR=./output AUDIO_FORMAT=mp3
4. 创建输出目录：
   mkdir -p output

🚀 运行服务器

您可以使用我们支持所有实现的新 CLI 工具运行服务器：

🔌 与 Cursor AI 集成

Cursor可以通过SSE接口与Resemble AI语音生成服务器进行交互：

1. 在 Cursor 中，前往“设置”→“AI”→“MCP 服务器”
2. 单击“添加服务器”并输入 SSE URL： http://localhost:8083/sse （如果需要，调整端口）
3. 保存配置

🔌 与 Claude Desktop 集成

1. 在 Claude Desktop 设置中配置 MCP 服务器：
   { "mcpServers": { "resemble-ai": { "command": "python", "args": ["-m", "src.cli", "--implementation", "mcp"], "env": { "RESEMBLE_API_KEY": "your_api_key_here" }, "disabled": false, "autoApprove": [] } } }

🛠️ 工具文档

列表声音

列出 Resemble AI 所有可用的语音模型。

**参数：**无

返回：

• voices ：可用语音模型列表，包括 ID、名称、性别、语言、口音和描述

生成_tts

从文本生成语音音频。

参数：

• text （字符串，必需）：要转换为语音的文本
• voice_id （字符串，必需）：要使用的语音的 ID
• return_type （字符串，可选）：如何返回音频：“file”或“base64”（默认：“file”）
• output_filename （字符串，可选）：不带扩展名的输出文件名（默认值：自动生成的名称）

返回：

• success （布尔值）：操作是否成功
• message （字符串）：状态消息
• audio_data （字符串，可选）：Base64 编码的音频数据（如果 return_type 为“base64”）
• file_path （字符串，可选）：保存的音频文件的路径（如果 return_type 为“file”）

💬 示例提示

一旦连接到 Cursor 或 Claude Desktop，您可以使用如下提示：

列出可用的声音：

生成语音音频：

⚠️ 故障排除

• Python 版本问题：MCP 软件包需要 Python 3.10 或更高版本。请使用提供的安装脚本创建正确的环境。
• API 连接问题：请确保您使用的 API 端点正确。Resemble AI API 端点是https://app.resemble.ai/api/v2/ 。
• 身份验证错误：验证您的 API 密钥是否正确且未过期。
• 缺少项目：API 要求您的 Resemble 帐户中至少有一个项目。如有需要，请通过 Resemble AI 仪表板创建一个项目。
• Cursor SSE 连接错误：如果 Cursor 无法通过 SSE 连接，请确保：
  • 服务器正在指定端口上运行
  • 您正在使用正确的/sse端点
  • 没有防火墙阻止连接
  • 尝试重新启动服务器和 Cursor

📚 附加文档

有关更详细的文档，请参阅docs/目录中的文件。

📄 许可证

麻省理工学院