tts-mcp

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 <model> TTS model to use (default: "gpt-4o-mini-tts")
  -v, --voice <voice> Voice character (default: "alloy")
  -f, --format <format> Audio format (default: "mp3")
  --api-key <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:

• Open the Claude Desktop configuration file (typically at ~/Library/Application Support/Claude/claude_desktop_config.json)
• 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:

• Direct method (recommended for testing): Include it in the args array using the --api-key parameter
• 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.

• Restart Claude Desktop
• 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>       Text to convert
  -f, --file <path>       Path to input text file
  -o, --output <path>     Path to output audio file (required)
  -m, --model <n>         Model to use (default: "gpt-4o-mini-tts")
  -v, --voice <n>         Voice character (default: "alloy")
  -s, --speed <number>    Speech speed (0.25-4.0) (default: 1)
  --format <format>       Output format (default: "mp3")
  -i, --instructions <text> Additional instructions for speech generation
  --api-key <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