tts-mcp

A Model Context Protocol (MCP) server and command-line tool for high-quality text-to-speech generation using the OpenAI TTS API.

Main Features

• MCP Server: Integrate text-to-speech capabilities with Claude Desktop and other MCP-compatible clients
• Voice Options: Support for multiple voice characters (alloy, nova, echo, etc.)
• High-Quality Audio: Support for various output formats (MP3, WAV, OPUS, AAC)
• Customizable: Configure speech speed, voice character, and additional instructions
• CLI Tool: Also available as a command-line utility for direct text-to-speech conversion

Installation

Method 1: Install from Repository

# Clone the repository
git clone https://github.com/nakamurau1/tts-mcp.git
cd tts-mcp

# Install dependencies
npm install

# Optional: Install globally
npm install -g .

Method 2: Run Directly with npx (No Installation Required)

# Start the MCP server directly
npx tts-mcp tts-mcp-server --voice nova --model tts-1-hd

# Use the CLI tool directly
npx tts-mcp -t "Hello, world" -o hello.mp3

MCP Server Usage

The MCP server allows you to integrate text-to-speech functionality with Model Context Protocol (MCP) compatible clients like Claude Desktop.

Starting the MCP Server

# Start with default settings
npm run server

# Start with custom settings
npm run server -- --voice nova --model tts-1-hd

# Or directly with API key
node bin/tts-mcp-server.js --voice echo --api-key your-openai-api-key

MCP Server Options

Options:
  -V, --version       Display version information
  -m, --model  TTS model to use (default: "gpt-4o-mini-tts")
  -v, --voice  Voice character (default: "alloy")
  -f, --format  Audio format (default: "mp3")
  --api-key      OpenAI API key (can also be set via environment variable)
  -h, --help          Display help information

Integrating with MCP Clients

The MCP server can be used with Claude Desktop and other MCP-compatible clients. For Claude Desktop integration:

1. Open the Claude Desktop configuration file (typically at ~/Library/Application Support/Claude/claude_desktop_config.json)
2. Add the following configuration, including your OpenAI API key:

{
  "mcpServers": {
    "tts-mcp": {
      "command": "node",
      "args": ["full/path/to/bin/tts-mcp-server.js", "--voice", "nova", "--api-key", "your-openai-api-key"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

Alternatively, you can use npx for easier setup:

{
  "mcpServers": {
    "tts-mcp": {
      "command": "npx",
      "args": ["-p", "tts-mcp", "tts-mcp-server", "--voice", "nova", "--model", "gpt-4o-mini-tts"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

You can provide the API key in two ways:

1. Direct method (recommended for testing): Include it in the args array using the --api-key parameter
2. Environment variable method (more secure): Set it in the env object as shown above

Security Note: Make sure to secure your configuration file when including API keys.

3. Restart Claude Desktop
4. When you ask Claude to "read this text aloud" or similar requests, the text will be converted to speech

Available MCP Tools

• text-to-speech: Tool for converting text to speech and playing it

CLI Tool Usage

You can also use tts-mcp as a standalone command-line tool:

# Convert text directly
tts-mcp -t "Hello, world" -o hello.mp3

# Convert from a text file
tts-mcp -f speech.txt -o speech.mp3

# Specify custom voice
tts-mcp -t "Welcome to the future" -o welcome.mp3 -v nova

CLI Tool Options

Options:
  -V, --version           Display version information
  -t, --text        Text to convert
  -f, --file        Path to input text file
  -o, --output      Path to output audio file (required)
  -m, --model          Model to use (default: "gpt-4o-mini-tts")
  -v, --voice          Voice character (default: "alloy")
  -s, --speed     Speech speed (0.25-4.0) (default: 1)
  --format        Output format (default: "mp3")
  -i, --instructions  Additional instructions for speech generation
  --api-key          OpenAI API key (can also be set via environment variable)
  -h, --help              Display help information

Supported Voices

The following voice characters are supported:

• alloy (default)
• ash
• coral
• echo
• fable
• onyx
• nova
• sage
• shimmer

Supported Models

• tts-1
• tts-1-hd
• gpt-4o-mini-tts (default)

Output Formats

The following output formats are supported:

• mp3 (default)
• opus
• aac
• flac
• wav
• pcm

Environment Variables

You can also configure the tool using system environment variables:

OPENAI_API_KEY=your-api-key-here

License

MIT