类AI语音生成MCP服务器

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

特征

• 使用 Resemble AI 的声音从文本生成语音音频

• 列出可用的语音模型

• 将音频作为本地文件或 base64 编码字符串返回

• 多种连接方式：

  • SSE 传输- 基于网络的服务器发送事件（默认）

  • StdIO Transport - 直接进程通信

Related MCP server: MCP Sound Tool

设置说明

先决条件

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

连接到光标

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/目录中找到示例用法。

📁 存储库结构

.
├── 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+ 环境：

   # 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 工具运行服务器：

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

🛠️ 工具文档

列表声音

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

列出可用的声音：

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

📄 许可证

麻省理工学院