Resemble MCP

类似于AI语音生成MCP服务器

服务器实现 类似AI 与集成的语音生成API 克劳德 和 光标 使用模型上下文协议（MCP）。

特性

• 使用Resemble AI的语音从文本生成语音音频
• 列出可用的语音模型
• 将音频作为本地文件或base64编码字符串返回
• 多种连接方式：

- SSE 运输 -基于网络的服务器发送事件（默认） - 标准运输 -直接过程沟通

安装说明

先决条件

• Python 3.10或更高版本
• 类似AI API密钥（在注册 类似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

连接到克劳德桌面

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 运输 当您想单独运行服务器或在其他计算机上运行服务器时
• 使用 标准运输 当您希望Claude/Cursor为您管理服务器进程时

例子

示例用法可以在 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

1. 安装依赖项：

   pip install uvicorn fastapi python-dotenv requests pydantic httpx sse-starlette
   pip install git+https://github.com/modelcontextprotocol/python-sdk.git

1. 设置环境变量：

   cp .env.example .env

编辑 .env 文件并添加您的Resemble AI API密钥：

   RESEMBLE_API_KEY=your_api_key_here

可选：自定义音频输出设置

   OUTPUT_DIR=./output
   AUDIO_FORMAT=mp3

1. 创建输出目录：

   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. 在光标中，转到设置→ 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 （string，必填）：要转换为语音的文本
• voice_id （string，必填）：要使用的语音ID
• return_type （string，可选）：如何返回音频：'file'或'base64'（默认值：'file\]）
• output_filename （字符串，可选）：不带扩展名的输出文件名（默认：自动生成的名称）

退货：

• success （boolean）：操作是否成功
• message （string）：状态消息
• 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端点。类似人工智能API端点为 https://app.resemble.ai/api/v2/.
• 身份验证错误：验证您的API密钥是否正确且未过期。
• 缺失的项目：API要求您的Resemble帐户中至少有一个项目。如果需要，可以通过Resemble AI仪表板创建项目。
• 游标SSE连接错误：如果Cursor无法通过SSE连接，请确保：

- 服务器正在指定端口上运行 - 您使用的是正确的 /sse 端点 - 没有防火墙阻止连接 - 尝试重新启动服务器和Cursor

📚 其他文件

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

📄 许可证

麻省理工学院