osc-pv/claude-text-to-speech

Text-to-Speech for Claude

A text-to-speech application that converts Claude's responses to voice using Eleven Labs API. Only works on Desktop App

Overview

This project provides multiple ways to get voice output from Claude:

• MCP Server for Claude Desktop (Mac/Windows app)
• Command-line tool for direct TTS conversion
• Response processor for piping text through TTS

Features

• 🎙️ High-quality text-to-speech using Eleven Labs
• 🔌 MCP server integration with Claude Desktop
• 🧹 Automatic markdown cleanup (removes code blocks, formatting)
• ⚙️ Configurable voice selection
• 🔐 Secure API key storage via .env file

Setup

1. Install Dependencies

pip install -r requirements.txt
brew install ffmpeg  # Required for audio playback

2. Configure API Key

Create a .env file in the project directory:

ELEVENLABS_API_KEY=your-api-key-here
ELEVENLABS_VOICE_ID=your-voice-id  # Optional, defaults to Bella

Get your API key from Eleven Labs.

3. Setup Claude Desktop (Optional)

To enable voice responses in Claude Desktop, the MCP server is already configured in:

~/Library/Application Support/Claude/claude_desktop_config.json

Restart Claude Desktop after any changes.

Components

1. tts_reader.py

Basic text-to-speech converter.

Usage:

# Read text from command line
python tts_reader.py "Hello, this is Claude speaking"

# Read from stdin
echo "Hello world" | python tts_reader.py -

# Pipe from file
cat response.txt | python tts_reader.py -

2. speak_response.py

Enhanced TTS with markdown cleanup for Claude responses.

Usage:

# Clean and speak markdown text
echo "**Bold text** with `code`" | python speak_response.py

# Direct text
python speak_response.py "Your text here"

Features:

• Removes code blocks (replaced with "[code block]")
• Strips markdown formatting (bold, italic, links)
• Cleans up excessive whitespace

3. mcp_server.py

MCP (Model Context Protocol) server for Claude Desktop integration.

Provides:

• speak tool - Converts text to speech within Claude Desktop

Usage in Claude Desktop:

• "Answer me by voice: [question]"
• "Use the speak tool: [text]"
• "Read this aloud: [text]"

4. speak.sh

Convenience shell script wrapper.

Usage:

./speak.sh "Your text here"

Platform Support

Configuration

Voice Selection

List available voices at Eleven Labs Voice Library.

Update .env with your preferred voice ID:

ELEVENLABS_VOICE_ID=your-voice-id-here

MCP Server Configuration

Located at: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "text-to-speech": {
      "command": "/opt/anaconda3/bin/python",
      "args": ["/path/to/text2speech/mcp_server.py"],
      "env": {
        "ELEVENLABS_API_KEY": "your-key",
        "ELEVENLABS_VOICE_ID": "your-voice-id"
      }
    }
  }
}

Troubleshooting

Audio doesn't play

• Ensure ffmpeg is installed: brew install ffmpeg
• Check that ffplay is in PATH: which ffplay

MCP server not connecting

• Verify claude_desktop_config.json exists and is valid JSON
• Check Python path matches your installation: which python
• Restart Claude Desktop completely (quit and reopen)
• Check logs: ~/Library/Logs/Claude/main.log

API key errors

• Verify .env file exists in project directory
• Check API key is valid at Eleven Labs
• Ensure no extra spaces or quotes in .env file

Requirements

• Python 3.8+
• ffmpeg (for audio playback)
• Eleven Labs API key
• Claude Desktop 0.7+ (for MCP support)

Files

• tts_reader.py - Basic TTS tool
• speak_response.py - TTS with markdown cleanup
• mcp_server.py - MCP server for Claude Desktop
• speak.sh - Shell wrapper script
• .env - API credentials (not committed to git)
• .gitignore - Excludes .env and Python cache files
• requirements.txt - Python dependencies

Security

• API keys are stored in .env file
• .env is excluded from git via .gitignore
• Never commit API keys to version control

License

This project uses the Eleven Labs API. See Eleven Labs Terms for API usage terms.