Resemble AI 语音生成 MCP 服务器

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

功能

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

安装说明

前提条件

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

环境设置

选项 1：使用 Conda（推荐）

# 运行设置脚本
./scripts/setup_environment.sh

# 激活环境
conda activate resemble_mcp

选项 2：使用虚拟环境

# 运行设置脚本
./scripts/setup_venv.sh

# 激活环境
source venv/bin/activate

配置

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

export RESEMBLE_API_KEY="your_api_key_here"

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

RESEMBLE_API_KEY=your_api_key_here

运行服务器

使用运行脚本（推荐）

选择您喜欢的实现：

# 运行带有 SSE 传输的 MCP SDK 实现（默认）
./run_server.sh mcp 8083

# 运行 HTTP 实现
./run_server.sh http 8083

# 使用 StdIO 传输运行（用于直接进程通信）
./run_server.sh stdio

直接使用 CLI

# 运行带有 SSE 传输的 MCP SDK 实现
python -m src.cli --implementation mcp --port 8083

# 使用 StdIO 传输运行
python -m src.cli --implementation stdio

连接到 Claude Desktop

SSE 传输连接

创建一个 claude_desktop_config.json 文件：

{
  "mcpServers": {
    "resemble-ai": {
      "sseUrl": "http://localhost:8083/sse"
    }
  }
}

StdIO 传输连接

创建一个 claude_desktop_config.json 文件：

{
  "mcpServers": {
    "resemble-ai": {
      "command": "python",
      "args": ["-m", "src.cli", "--implementation", "stdio"],
      "env": {
        "RESEMBLE_API_KEY": "your_api_key_here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

连接到 Cursor

SSE 传输连接

1. 转到 Settings → AI → MCP Servers
2. 点击 "Add Server"
3. 选择 "SSE" 作为连接类型
4. 将 URL 设置为：http://localhost:8083/sse

StdIO 传输连接

1. 转到 Settings → AI → MCP Servers
2. 点击 "Add Server"
3. 选择 "Subprocess" 作为连接类型
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 vs. SSE 传输

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

示例

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

📁 仓库结构

.
├── src/                 # 服务器实现的源代码
│   ├── resemble_mcp_server.py    # MCP SDK 实现（推荐）
│   ├── resemble_http_server.py   # HTTP API 实现
│   ├── resemble_ai_server.py     # 直接 API 实现
│   ├── resemble_ai_sdk_server.py # Resemble SDK 实现
│   └── cli.py           # 用于运行服务器的 CLI 工具
├── tests/               # 测试脚本
├── docs/                # 文档
├── examples/            # 示例用法和工具
├── scripts/             # 设置和实用程序脚本
├── output/              # 生成的音频输出目录
├── .env.example         # 示例环境配置
├── requirements.txt     # Python 依赖项
└── README.md            # 此文件

🚀 快速设置

提供了两个设置脚本，使安装变得容易：

使用 Conda（推荐）

# 使脚本可执行
chmod +x scripts/setup_environment.sh

# 运行设置脚本
./scripts/setup_environment.sh

使用 Python venv

# 使脚本可执行
chmod +x scripts/setup_venv.sh

# 运行设置脚本
./scripts/setup_venv.sh

任一脚本都将：

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

手动安装

如果您喜欢手动设置：

1. 创建一个 Python 3.10+ 环境：

   # 使用 conda
   conda create -n resemble_mcp python=3.10
   conda activate resemble_mcp
   
   # OR 使用 venv（已安装 Python 3.10+）
   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 工具运行服务器，该工具支持所有实现：

# 如果尚未激活，请激活您的环境
conda activate resemble_mcp
# OR
source venv/bin/activate

# 运行 MCP SDK 实现（推荐）
python -m src.cli --implementation mcp --port 8083

# 其他实现：
# HTTP API 实现
python -m src.cli --implementation http --port 8083
# 直接 API 实现
python -m src.cli --implementation direct --port 8083
# Resemble SDK 实现
python -m src.cli --implementation sdk --port 8083

🔌 与 Cursor AI 集成

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

1. 在 Cursor 中，转到 Settings → AI → MCP Servers
2. 点击 "Add Server" 并输入 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": []
       }
     }
   }
   

🛠️ 工具文档

list_voices

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

参数： 无

返回：

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

generate_tts

从文本生成语音音频。

参数：

• text (string, required): 要转换为语音的文本
• voice_id (string, required): 要使用的语音的 ID
• return_type (string, optional): 如何返回音频：'file' 或 'base64' (default: 'file')
• output_filename (string, optional): 输出文件的文件名，不带扩展名（默认：自动生成名称）

返回：

• success (boolean): 操作是否成功
• message (string): 状态消息
• audio_data (string, optional): Base64 编码的音频数据（如果 return_type 为 'base64'）
• file_path (string, optional): 保存的音频文件的路径（如果 return_type 为 'file'）

💬 示例提示

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

列出可用的声音：

List all available voice models from Resemble AI.

生成语音音频：

Generate audio of the text "Hello, this is a test of the Resemble AI voice generation system" using a male English voice.

⚠️ 故障排除

• 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/ 目录中的文件。

📄 许可证

MIT