openai-elevenlabs-tts-mcp-server/README.md

MCP server that converts text to speech using OpenAI for transformation and ElevenLabs for voice synthesis

# OpenAI + ElevenLabs TTS MCP Server

![MCP Server](https://img.shields.io/badge/MCP-Server-blue)
![License](https://img.shields.io/badge/license-MIT-green)
[![Website](https://img.shields.io/badge/Website-feathered.io-purple)](https://feathered.io)

A powerful Model Context Protocol (MCP) server that I created to convert text to speech using OpenAI for text transformation and ElevenLabs for text-to-speech conversion.

## 🌟 Features

- **Text Transformation**: Uses OpenAI's GPT-4o to transform plain text into engaging, light-hearted scripts
- **Text-to-Speech Conversion**: Leverages ElevenLabs' high-quality voice synthesis API
- **File Input Support**: Process text directly or from .txt files
- **Persistent Storage**: Automatically saves generated audio files to the outputs directory
- **MCP Integration**: Seamlessly integrates with Claude and other MCP-compatible AI assistants

## 📋 Prerequisites

- Node.js (v16 or higher)
- OpenAI API key
- ElevenLabs API key

## 🚀 Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/Gitmaxd/openai-elevenlabs-tts-mcp-server.git
   cd openai-elevenlabs-tts-mcp-server
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Build the server:
   ```bash
   npm run build
   ```

4. Set up your API keys as environment variables:
   ```bash
   export OPENAI_API_KEY="your-openai-api-key"
   export ELEVENLABS_API_KEY="your-elevenlabs-api-key"
   ```

## 🔧 Configuration

### Output Directory

By default, audio files are saved to the `outputs` directory in the current working directory. You can customize the output location by setting the `TTS_OUTPUT_DIR` environment variable:

```bash
export TTS_OUTPUT_DIR="/path/to/custom/output/directory"
```

### Claude Desktop Integration

To use with Claude Desktop, add the server configuration to your Claude Desktop config file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "openai-elevenlabs-tts-mcp-server": {
      "command": "/absolute/path/to/openai-elevenlabs-tts-mcp-server/build/index.js"
    }
  }
}
```

## 🛠️ Available Tools

### generate_audio

Converts text to speech using OpenAI for transformation and ElevenLabs for TTS.

**Parameters**:
- `text` (string, required): Text content or path to a .txt file to convert to speech

**Example Usage in Claude**:
```
I'd like to convert this text to speech: "Hello world, this is a test of the text-to-speech system."
```

## 🧪 Development

For development with auto-rebuild:
```bash
npm run watch
```

### Debugging

Since MCP servers communicate over stdio, debugging can be challenging. I recommend using the MCP Inspector:

```bash
npm run inspector
```

The Inspector will provide a URL to access debugging tools in your browser.

## 📁 Project Structure

```
.
├── src/
│   └── index.ts         # Main server implementation
├── build/               # Compiled JavaScript files
├── outputs/             # Generated audio files
├── package.json         # Project dependencies and scripts
└── README.md            # This documentation
```

## 🔄 How It Works

1. The server receives a text input (direct text or file path)
2. OpenAI transforms the text into an engaging script
3. ElevenLabs converts the transformed text to speech
4. The audio file is saved to the outputs directory
5. The server returns the path to the generated audio file

## 📚 About MCP (Model Context Protocol)

The Model Context Protocol (MCP) is an open standard that enables AI assistants like Claude to interact with external tools and services. MCP servers provide a standardized way for AI models to access capabilities beyond their training data, such as accessing real-time information or controlling external systems.

Learn more about MCP at [modelcontextprotocol.github.io](https://modelcontextprotocol.github.io/).

## 👨‍💻 Created by

This MCP Server was created by me, [GitMaxd](https://twitter.com/GitMaxd).

## 📄 License

This project is open source and available under the MIT License.

## 🔗 Links

- Homepage: [https://feathered.io](https://feathered.io)
- GitHub Repository: [https://github.com/Gitmaxd/openai-elevenlabs-tts-mcp-server](https://github.com/Gitmaxd/openai-elevenlabs-tts-mcp-server)