Keeping you up to date on AI and Model Context Protocol (MCP)

Resemble AI Voice Generation MCP Server

A server implementation for the Resemble AI voice generation API that integrates with Claude and Cursor 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)

Environment Setup

Option 1: Using Conda (Recommended)

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

## Activate the environment
conda activate resemble_mcp

Option 2: Using Virtual Environment

## 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:

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:

## 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

## 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:

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

StdIO Transport Connection

Create a claude_desktop_config.json file:

{
  "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

Go to Settings → AI → MCP Servers
Click "Add Server"
Select "SSE" as the connection type
Set the URL to: http://localhost:8083/sse

StdIO Transport Connection

Go to Settings → AI → MCP Servers
Click "Add Server"
Select "Subprocess" as the connection type
Set the command to: python -m src.cli --implementation stdio
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:

Check that the server is running
Verify the correct URL is configured
Check that your API key is valid
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)

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

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

Using Python venv

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

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

Either script will:

Create a Python 3.10+ environment
Install all required dependencies
Set up a template .env file
Create the output directory for audio files

Manual Installation

If you prefer to set up manually:

Create a Python 3.10+ environment:

# 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

Install dependencies:

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

Set up your environment variables:
```
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
```
Create output directory:
```
mkdir -p output
```

🚀 Running the Server

You can run the server using our new CLI tool which supports all implementations:

## 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:

In Cursor, go to Settings → AI → MCP Servers
Click "Add Server" and enter the SSE URL: http://localhost:8083/sse (adjust port if needed)
Save the configuration

🔌 Integrating with Claude Desktop

Configure the MCP Server in Claude Desktop settings:

{
  "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