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)

Option 2: Using Virtual Environment

Configuration

Set your Resemble AI API key as an environment variable:

Alternatively, create a .env file in the project root with the following content:

Running the Server

Using the Run Script (Recommended)

Choose your preferred implementation:

Using the CLI Directly

Connecting to Claude Desktop

SSE Transport Connection

Create a claude_desktop_config.json file:

StdIO Transport Connection

Create a claude_desktop_config.json file:

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

🚀 Quick Setup

Two setup scripts are provided to make installation easy:

Using Conda (Recommended)

Using Python venv

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:
   # 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:
   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:
   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:
   mkdir -p output

🚀 Running the Server

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

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

Generating voice audio:

⚠️ 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