Resemble AI 语音生成 MCP 服务器

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

功能

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

设置说明

先决条件

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

环境设置

选项 1：使用 Conda（推荐）

# Run the setup script
./scripts/setup_environment.sh

# Activate the environment
conda activate resemble_mcp

选项 2：使用虚拟环境

# Run the setup script
./scripts/setup_venv.sh

# Activate the environment
source venv/bin/activate

配置

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

export RESEMBLE_API_KEY="your_api_key_here"

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

RESEMBLE_API_KEY=your_api_key_here

运行服务器

使用运行脚本（推荐）

选择您偏好的实现方式：

# Run the MCP SDK implementation with SSE transport (default)
./run_server.sh mcp 8083

# Run the HTTP implementation
./run_server.sh http 8083

# Run with StdIO transport (for direct process communication)
./run_server.sh stdio

直接使用 CLI

# Run the MCP SDK implementation with SSE transport
python -m src.cli --implementation mcp --port 8083

# Run with StdIO transport
python -m src.cli --implementation stdio

连接到 Claude 桌面版

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. 转到设置 → 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 传输
• 当您希望 Claude/Cursor 为您管理服务器进程时，请使用 StdIO 传输

示例

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

📁 仓库结构

.
├── src/                 # Source code for the server implementations
│   ├── resemble_mcp_server.py    # MCP SDK implementation (recommended)
│   ├── resemble_http_server.py   # HTTP API implementation
│   ├── resemble_ai_server.py     # Direct API implementation
│   ├── resemble_ai_sdk_server.py # Resemble SDK implementation
│   └── cli.py           # CLI tool for running the server
├── tests/               # Test scripts
├── docs/                # Documentation
├── examples/            # Example usage and tools
├── scripts/             # Setup and utility scripts
├── output/              # Generated audio output directory
├── .env.example         # Example environment configuration
├── requirements.txt     # Python dependencies
└── README.md            # This file

🚀 快速设置

提供了两个设置脚本以简化安装过程：

使用 Conda（推荐）

# Make the script executable
chmod +x scripts/setup_environment.sh

# Run the setup script
./scripts/setup_environment.sh

使用 Python venv

# Make the script executable
chmod +x scripts/setup_venv.sh

# Run the setup script
./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
   
   # 或者使用 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 工具来运行支持所有实现的服务器：

# Activate your environment if not already activated
conda activate resemble_mcp
# OR
source venv/bin/activate

# Run the MCP SDK implementation (recommended)
python -m src.cli --implementation mcp --port 8083

# Other implementations:
# HTTP API implementation
python -m src.cli --implementation http --port 8083
# Direct API implementation
python -m src.cli --implementation direct --port 8083
# Resemble SDK implementation
python -m src.cli --implementation sdk --port 8083

🔌 与 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": []
       }
     }
   }
   

🛠️ 工具文档

list_voices

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

参数: 无

返回:

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

generate_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，您可以使用如下提示：

列出可用的语音：

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