README.md•10.4 kB
# Resemble AI Voice Generation MCP Server
A server implementation for the [Resemble AI](https://www.resemble.ai/) voice generation API that integrates with [Claude](https://www.anthropic.com/claude) and [Cursor](https://cursor.sh/) using the Model Context Protocol (MCP).
## Features
- Generate voice audio from text using Resemble AI's voices
- List available voice models
- Return audio as local file or base64 encoded string
- Multiple connection methods:
- **SSE Transport** - Network-based Server-Sent Events (default)
- **StdIO Transport** - Direct process communication
## Setup Instructions
### Prerequisites
- Python 3.10 or higher
- Resemble AI API key (sign up at [Resemble AI](https://www.resemble.ai/))
### Environment Setup
#### Option 1: Using Conda (Recommended)
```bash
# Run the setup script
./scripts/setup_environment.sh
# Activate the environment
conda activate resemble_mcp
```
#### Option 2: Using Virtual Environment
```bash
# Run the setup script
./scripts/setup_venv.sh
# Activate the environment
source venv/bin/activate
```
### Configuration
Set your Resemble AI API key as an environment variable:
```bash
export RESEMBLE_API_KEY="your_api_key_here"
```
Alternatively, create a `.env` file in the project root with the following content:
```
RESEMBLE_API_KEY=your_api_key_here
```
## Running the Server
### Using the Run Script (Recommended)
Choose your preferred implementation:
```bash
# 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
```
### Using the CLI Directly
```bash
# 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
```
## Connecting to Claude Desktop
### SSE Transport Connection
Create a `claude_desktop_config.json` file:
```json
{
"mcpServers": {
"resemble-ai": {
"sseUrl": "http://localhost:8083/sse"
}
}
}
```
### StdIO Transport Connection
Create a `claude_desktop_config.json` file:
```json
{
"mcpServers": {
"resemble-ai": {
"command": "python",
"args": ["-m", "src.cli", "--implementation", "stdio"],
"env": {
"RESEMBLE_API_KEY": "your_api_key_here"
},
"disabled": false,
"autoApprove": []
}
}
}
```
## Connecting to Cursor
### SSE Transport Connection
1. Go to Settings → AI → MCP Servers
2. Click "Add Server"
3. Select "SSE" as the connection type
4. Set the URL to: `http://localhost:8083/sse`
### StdIO Transport Connection
1. Go to Settings → AI → MCP Servers
2. Click "Add Server"
3. Select "Subprocess" as the connection type
4. Set the command to: `python -m src.cli --implementation stdio`
5. Optionally add environment variables:
- `RESEMBLE_API_KEY`: Your Resemble AI API key
## Available Tools
### `list_voices`
Lists available voice models from Resemble AI.
### `generate_tts`
Generates voice audio from text.
Parameters:
- `text`: The text to convert to speech
- `voice_id`: ID of the voice to use
- `return_type`: How to return the audio: 'file' or 'base64' (optional, default: 'file')
- `output_filename`: Filename for the output without extension (optional)
## Implementation Details
The project includes several implementations:
- `src/resemble_mcp_server.py`: Uses the MCP SDK with SSE transport
- `src/resemble_stdio_server.py`: Uses StdIO transport for direct process communication
- `src/resemble_http_server.py`: HTTP implementation with SSE (fallback)
- `src/resemble_ai_server.py`: Direct API implementation
- `src/resemble_ai_sdk_server.py`: Implementation using the official Resemble SDK
## Troubleshooting
### MCP SDK Import Errors
If you encounter issues importing the MCP SDK, the server will automatically fall back to the HTTP implementation with SSE transport.
### Connection Issues
If Claude or Cursor cannot connect to the server:
1. Check that the server is running
2. Verify the correct URL is configured
3. Check that your API key is valid
4. Look for errors in the server logs
### StdIO vs. SSE Transport
- Use **SSE Transport** when you want to run the server separately, or on a different machine
- Use **StdIO Transport** when you want Claude/Cursor to manage the server process for you
## Examples
Example usage can be found in the `examples/` directory.
## 📁 Repository Structure
```
.
├── 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
```
## 🚀 Quick Setup
Two setup scripts are provided to make installation easy:
### Using Conda (Recommended)
```bash
# Make the script executable
chmod +x scripts/setup_environment.sh
# Run the setup script
./scripts/setup_environment.sh
```
### Using Python venv
```bash
# Make the script executable
chmod +x scripts/setup_venv.sh
# Run the setup script
./scripts/setup_venv.sh
```
Either script will:
1. Create a Python 3.10+ environment
2. Install all required dependencies
3. Set up a template .env file
4. Create the output directory for audio files
## Manual Installation
If you prefer to set up manually:
1. Create a Python 3.10+ environment:
```bash
# 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. Install dependencies:
```bash
pip install uvicorn fastapi python-dotenv requests pydantic httpx sse-starlette
pip install git+https://github.com/modelcontextprotocol/python-sdk.git
```
3. Set up your environment variables:
```bash
cp .env.example .env
```
Edit the `.env` file and add your Resemble AI API key:
```
RESEMBLE_API_KEY=your_api_key_here
```
Optional: Customize audio output settings
```
OUTPUT_DIR=./output
AUDIO_FORMAT=mp3
```
4. Create output directory:
```bash
mkdir -p output
```
## 🚀 Running the Server
You can run the server using our new CLI tool which supports all implementations:
```bash
# 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
```
## 🔌 Integrating with Cursor AI
Cursor can interact with the Resemble AI voice generation server through the SSE interface:
1. In Cursor, go to Settings → AI → MCP Servers
2. Click "Add Server" and enter the SSE URL: `http://localhost:8083/sse` (adjust port if needed)
3. Save the configuration
## 🔌 Integrating with Claude Desktop
1. Configure the MCP Server in Claude Desktop settings:
```json
{
"mcpServers": {
"resemble-ai": {
"command": "python",
"args": ["-m", "src.cli", "--implementation", "mcp"],
"env": {
"RESEMBLE_API_KEY": "your_api_key_here"
},
"disabled": false,
"autoApprove": []
}
}
}
```
## 🛠️ Tool Documentation
### list_voices
Lists all available voice models from Resemble AI.
**Parameters:** None
**Returns:**
- `voices`: List of available voice models with IDs, names, genders, languages, accents, and descriptions
### generate_tts
Generates voice audio from text.
**Parameters:**
- `text` (string, required): The text to convert to speech
- `voice_id` (string, required): The ID of the voice to use
- `return_type` (string, optional): How to return the audio: 'file' or 'base64' (default: 'file')
- `output_filename` (string, optional): Filename for the output without extension (default: auto-generated name)
**Returns:**
- `success` (boolean): Whether the operation was successful
- `message` (string): Status message
- `audio_data` (string, optional): Base64-encoded audio data (if return_type is 'base64')
- `file_path` (string, optional): Path to the saved audio file (if return_type is 'file')
## 💬 Example Prompts
Once connected to Cursor or Claude Desktop, you can use prompts like:
**Listing available voices:**
```
List all available voice models from Resemble AI.
```
**Generating voice audio:**
```
Generate audio of the text "Hello, this is a test of the Resemble AI voice generation system" using a male English voice.
```
## ⚠️ Troubleshooting
- **Python Version Issues**: The MCP package requires Python 3.10 or newer. Use the provided setup scripts to create the correct environment.
- **API Connection Issues**: Make sure you're using the correct API endpoint. The Resemble AI API endpoint is `https://app.resemble.ai/api/v2/`.
- **Authentication Errors**: Verify your API key is correct and not expired.
- **Missing Projects**: The API requires at least one project in your Resemble account. Create a project through the Resemble AI dashboard if needed.
- **Cursor SSE Connection Errors**: If Cursor fails to connect via SSE, make sure:
- The server is running on the specified port
- You're using the correct `/sse` endpoint
- No firewall is blocking the connection
- Try restarting both the server and Cursor
## 📚 Additional Documentation
For more detailed documentation, see the files in the `docs/` directory.
## 📄 License
MIT